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Preface 


Intended Audience 


This manual is intended for all users of the OpenVMS operating system. It 
includes descriptions of all DIGITAL Command Language (DCL) commands and 
lexical functions. If a command has any restrictions or requires special privileges, 
they are noted in reference information for that command. 


Readers of this manual should be familiar with the material covered in the 
OpenVMS User’s Manual. 


Document Structure 


This manual contains detailed descriptions of each command and lexical function. | 
The commands are listed in alphabetical order, with the command name 
appearing at the top of every page. The lexical functions are grouped under the 
heading Lexical Functions (after the JOB command description) and are listed 
alphabetically within that grouping; the lexical function name appears at the top 
of each page. 


The hard copy of the OpenVMS DCL Dictionary is a two-part manual. The first 
contains commands beginning with the letters A to M (including the lexical 
functions); The second part contains commands beginning with the letters N to 
Z. The Table of Contents and Index are comprehensive: they include both parts. 
The Bookreader copy of the OpenVMS DCL Dictionary is one manual. 


Appendix A lists the obsolete DCL commands and the current services that 
replace them. 


The commands that invoke language compilers and other OpenVMS optional 
software products are not included in this manual; they are included in the 
documentation provided with those products. 


Related Documents 


For an introduction to the OpenVMS operating system and for information 
on using DCL, see the OpenVMS User’s, Manual. This manual is especially 
recommended for novice users or users lacking experience with interactive 

computer systems. 


The OpenVMS User’s Manual provides an overview of DCL command language 
concepts and defines and illustrates good practices in constructing command 
procedures with DCL commands and lexical functions. 


See the various utilities reference manuals for detailed information on utilities. 
These manuals describe the DCL commands that invoke the various utilities, 
describe any commands that you can enter while running a utility, and provide 
reference information. The OpenVMS DCL Dictionary only provides a brief 
description and format information of each utility. 
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For message descriptions, use the online Help Message utility or refer to the 


OpenVMS system messages documentation. 


Reader’s Comments 


Digital welcomes your comments on this manual. 


Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and 


send us your comments by: 


Internet openvmsdoc@zko.mts.dec.com 
Fax 603 881-0120, Attention: OpenVMS Documentation, ZK03-4/U08 
Mail OpenVMS Documentation Group, ZKO3-4/U08 


110 Spit Brook Rd. 
Nashua, NH 03062-2698 


How To Order Additional Documentation 


Use the following table to order additional documentation or information. 
If you need help deciding which documentation best meets your needs, call 


800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Location Call Fax 
U.S.A. DECdirect Fax: 800-234-2298 
800-DIGITAL 
800-344—4825 
Puerto Rico 809-781-0505 Fax: 809-749-8300 
Canada 800-267-6215 Fax: 613-592-1946 


International 


Internal Orders DTN: 264—4446 Fax: 603-884-3960 
603-884-4446 


Conventions 


The name of the OpenVMS AXP operating system has been changed to OpenVMS 
Alpha. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS 


viii 


Alpha or Alpha. 


Write 

Digital Equipment Corporation 
P.O. Box CS2008 

Nashua, NH 03061 


Digital Equipment Caribbean, Inc. 

3 Digital Plaza, 1st Street, Suite 200 
P.O. Box 11038 

Metro Office Park 

San Juan, Puerto Rico 00910-2138 


Digital Equipment of Canada, Ltd. 
Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 
Attn: DECdirect Sales 


Local Digital subsidiary or 
approved distributor 


USS. Software Supply Business 
Digital Equipment Corporation 
10 Cotton Road 

Nashua, NH 03063-1260 


ZK-7654A-GE 


The following conventions are used to identify information specific to OpenVMS 


Alpha or to OpenVMS VAX: 


The Alpha icon denotes the beginning of information 
specific to OpenVMS Alpha. 





The VAX icon denotes the beginning of information 
> specific to OpenVMS VAX. 
The diamond symbol denotes the end of a section of 
4 information specific to OpenVMS Alpha or to OpenVMS 
VAX. 


In this manual, every use of DECwindows and DECwindows Motif refers to 
DECwindows Motif for OpenVMS software. 


The following conventions are also used in this manual: 


Ctrl/x A sequence such as Ctrl/x indicates that you must hold down 
the key labeled Ctrl while you press another key or a pointing 
device button. 


PF1 (GOLD) x A sequence such as PF1 x indicates that you must first press 
and release the key labeled PF 1 (defined as the GOLD key), 
then press and release another key or a pointing device button. 


The GOLD key definition is often mapped to the PF1 key on 
the keypad. GOLD key sequences can also have a slash (/), 
dash (—), or underscore (_) as a delimiter in EVE commands. 


In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


Horizontal ellipsis points in examples indicate one of the 
following possibilities: 


e Additional optional arguments in a statement have been 
omitted. 


e The preceding item or items can be repeated one or more 
times. 


e Additional parameters, values, or other information can be 
entered. 


Vertical ellipsis points indicate the omission of items from 
a code example or command format; the items are omitted 
because they are not important to the topic being discussed. 


() In command format descriptions, parentheses indicate that, if 
you choose more than one option, you must enclose the choices 
in parentheses. 


[J In command format descriptions, brackets indicate optional 
elements. You can choose one, none, or all of the options. 
(Brackets are not optional, however, in the syntax of a directory 
name in an OpenVMS file specification or in the syntax of a 
substring specification in an assignment statement.) 


{ } In command format descriptions, braces indicate a required 
choice of options; you must choose one of the options listed. 


boldface text Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 


Boldface text is also used to show user input in Bookreader 
versions of the manual. 


italic text 


UPPERCASE TEXT 


numbers 


Italic text indicates important information, complete titles of 
manuals, or variables. Italic text also represents information 
that can vary in system messages (for example, Internal error 
number), command lines (for example, /PRODUCER=name), 
and command parameters in text. 


Uppercase text indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 


A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 


All numbers in text are assumed to be decimal unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 


The contents of the display examples for certain commands described in this 
manual may differ slightly from the actual output provided by these commands 
on your system. However, when the behavior of a command differs significantly 
between Alpha and VAX, that behavior is described in text and rendered, as 
appropriate, in separate examples. 


= (Assignment Statement) | 


= (Assignment Statement) 
Defines a symbolic name for a character string or integer value. 


Format 
symbol-name =[=] expression 


symbol-name[bit-position,size] =[=] replacement-expression 


Note 


Digital advises against assigning a symbolic name that is already a DCL 

command name. Digital especially discourages the assignment of symbols 
such as IF, THEN, ELSE, and GOTO, which can affect the interpretation 
of command procedures. 


Parameters 


~ symbol-name 
Specifies a string of 1 to 255 characters for the symbol name. The name can 
contain any alphanumeric characters from the DEC Multinational character set, 
the underscore (_), and the dollar sign ($). However, the name must begin only 
with an alphabetic character (uppercase and lowercase characters are equivalent), 
an underscore, or a dollar sign. Using one equal sign (=) places the symbol name 
in the local symbol table for the current command level. Using two equal signs 
(==) places the symbol name in the global symbol table. 


expression 

Names the value on the right-hand side of an assignment statement. This 
parameter can consist of a character string, an integer, a symbol name, a lexical 
function, or a combination of these entities. The components of the expression are 
evaluated, and the result is assigned to the symbol. All literal character strings 
must be enclosed in quotation marks (“”). If the expression contains a symbol, 
the expression is evaluated using the symbol’s value. 


The result of expression evaluation is either a character string or a signed integer 
value. If the expression is evaluated as a string, the symbol is assigned a string 
value. If the expression is evaluated as an integer, the symbol is assigned an 
integer value. If the integer value exceeds the capacity of the 4-byte buffer that 
holds it, no error message is issued. 


For a summary of operators used in expressions, details on how to specify 
expressions, and details on how expressions are evaluated, see the OpenVMS 
User’s Manual. 


DCL uses a buffer that is 1024 bytes long to hold an assignment statement and 
to evaluate the expression. The length of the symbol name, the expression, and 
the expression’s calculations cannot exceed 1024 bytes. 


[bit-position,size] 

States that a binary overlay is to be inserted in the current 32-bit value of a 
symbol name. The current value of the symbol name is evaluated. Then, the 
specified number of bits is replaced by the result of the replacement expression. 
The bit position is the location relative to bit 0 at which the overlay is to occur. 
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If the symbol you are overlaying is an integer, then the bit position must be less 
than 32. The sum of the bit position and the size must be less than or equal to 
32. 


If the symbol you are overlaying is a string, then the bit position must be less 
than 6152. Because each character is represented using 8 bits, you can begin 
an overlay at any character through the 768th character. (The 768th character 
starts in bit position 6144.) The sum of the bit position and the size must be less 
than or equal to 6152. 


The size is the number of bits to be overlaid. If you specify a size that is greater 
than 32, DCL reduces the size to 32. 


The brackets are required notation; no spaces are allowed between the symbol 
name and the left bracket. Specify values for the bit position and size as integers. 


replacement-expression 
Specifies the value that is used to overlay the symbol you are modifying. Specify 
the replacement expression as an integer. 


If the symbol you are modifying is an integer, the replacement expression defines 
a bit pattern that is overlaid on the value assigned to the symbol. If the symbol 
you are modifying is a character string, the result of the replacement expression 
defines a bit pattern that is overlaid on the specified bits of the character string. 
If the symbol you are modifying is undefined, the result of the replacement 
expression is overlaid on a null string. 


Description 


Symbols defined using assignment statements allow you to extend the command 
language. At the interactive command level, you can use symbols to define 
synonyms for commands or command lines. In command procedure files, you can 
use symbols to provide for conditional execution and substitution of variables. 


The maximum number of symbols that can be defined at any time depends on the 
following: 


¢ The amount of space available to the command interpreter to contain symbol 
tables and labels for the current process. The amount of space is determined 
for each process by the system parameter CLISYMTBL. 


e The size of the symbol names and their values. The command interpreter 
allocates space for a symbol name and its value. In addition, a few bytes of 
overhead are allocated for each symbol. 


Examples 


1. §$ LIST == "DIRECTORY" 


The assignment statement in this example assigns the user-defined synonym 
LIST as a global symbol definition for the DCL command DIRECTORY. 
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$ COUNT = 0 

$ LOOP: | 

$ COUNT = COUNT + 1 

$ IF P'COUNT’ .EQS. "" THEN EXIT 
$ APPEND/NEW &P‘COUNT’ SAVE.ALL 
$ DELETE &P’COUNT’;* 

$ IF COUNT .LT. 8 THEN GOTO LOOP 


$ EXIT 


This command procedure, COPYDEL.COM, appends files (specified as 
parameters) to a file called SAVE.ALL. After a file has been appended, the 
command procedure deletes the file. Up to eight file names can be passed to 
the command procedure. The file names are assigned to the symbols P1, P2, 
and so on. 


The command procedure uses a counter to refer to parameters that are passed 
to it. Each time through the loop, the procedure uses an IF command to check 
whether the value of the current parameter is a null string. When the IF 
command is scanned, the current value of the symbol COUNT is concatenated 
with the letter P. The first time through the loop, the IF command tests P1; 
the second time through the loop it tests P2, and so on. After the expression 
P‘COUNT? is evaluated, the substitution of the file names that correspond to 
P1, P2, and so on is automatic within the context of the IF command. 


The APPEND and DELETE commands do not perform any substitution 
automatically, because they expect and require file specifications as input 
parameters. The ampersand (&) precedes the P*;COUNT?’ expression for 
these commands to force the appropriate symbol substitution. When these 
commands are initially seanned each time through the loop, COUNT is 
substituted with its current value. Then, when the commands execute, 
the ampersand causes another substitution: the first file specification is 
substituted for Pl, the second file specification is substituted for P2, and so 
on. 


To invoke this procedure, use the following command: 
$ @COPYDEL ALAMO.TXT BEST.DOC 


The files ALAMO.TXT and BEST.DOC are each appended to the file 
SAVE.ALL and are then deleted. 


$ A = 25 
$ CODE = 4 + FSINTEGER("6") - A 
$ SHOW SYMBOL CODE 
CODE = -15 HEX = FFFFFFF1 Octal = 1777761 


This example contains two assignment statements. The first assignment 
statement assigns the value 25 to the symbol A. The second assignment 
statement evaluates an expression containing an integer (4), a lexical function 
(FSINTEGER(“6”)), and the symbol A. The result of the expression, —15, is 
assigned to the symbol CODE. 


$ FILENAME = "JOBSEARCH" - "JOB" 
§ FILETYPE = ".OBJ" 
$ FILESPEC = FILENAME + FILETYPE 


$ TYPE ‘FILESPEC’ 


The first command in this example assigns the symbol FILENAME the value 
“SEARCH”. Notice that the string “SEARCH” is the result of the string 
reduction operation performed by the expression. The second command 
assigns the symbol FILETYPE the character string “.OBJ”. The symbols 
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FILENAME and FILETYPE are then added together in an expression 
assigned to the symbol FILESPEC. Because the values of the symbols 
FILENAME and FILETYPE are concatenated, the resultant value assigned 
to FILESPEC is the character string “SEARCH.OBJ”. The symbol FILESPEC 
is then used as a parameter for the TYPE command. The single quotation 
marks (‘’) request the command interpreter to replace the symbol FILESPEC 
with its value SEARCH.OBJ. Thus, the TYPE command types the file named 
SEARCH.OBJ. 


$ BELL[0,32] = X07 
$ SHOW SYMBOL BELL 
BELL = "" 


In this example, the symbol BELL is created with an arithmetic overlay 
assignment statement. Because the symbol BELL is previously undefined, 
the hexadecimal value 7 is inserted over a null character string and is 
interpreted as the ASCII code for the bell character on a terminal. When you 
issue the command SHOW SYMBOL BELL, the terminal beeps. 


If the symbol BELL had been previously defined with an integer value, the 
result of displaying BELL would have been to show its new integer value. 


$ $=34 

%DCL-W-NOCOMD, no command on line - reenter with alphabetic first 
character 

$ $$=34 

$ SHOW SYMBOL $$ 

%DCL-W-UNDSYM, undefined symbol - check validity and spelling 

$ SHOW SYMBOL $ 

$ = 34 Hex = 00000022 Octal = 00000000042 


If you begin a symbol name with the dollar sign ($), use two dollar signs ($$) 
because DCL discards the first instance of the dollar sign. 


:= (String Assignment) 


:= (String Assignment) 
Defines a symbolic name for a character string value. 


Format 
symbol-name :=[=] string 


symbol-namef[offset,size] :=[=] replacement-string 


Note 


Digital advises against assigning a symbolic name that is already a DCL 

command name. Digital especially discourages the assignment of symbols 
such as IF, THEN, ELSE, and GOTO, which can affect the interpretation 
of command procedures. 


Parameters 


symbol-name 

Specifies a string of 1 to 255 characters for the symbol name. The name can 
contain any alphanumeric characters from the DEC Multinational character 

set, the underscore (_), and the dollar sign ($). However, the name must begin 
only with an alphabetic character, an underscore, or a dollar sign. Using one 
equal sign (:=) places the symbol name in the local symbol table for the current 
command level. Using two equal signs (:==) places the symbol name in the global 
symbol table. 


string 

Names the character string value to be equated to the symbol. The string can 
contain any alphanumeric or special characters. DCL uses a buffer that is 1024 
bytes long to hold a string assignment statement. Therefore, the length of the 
symbol name, the string, and any symbol substitution within the string cannot 
exceed 1024 characters. 


With the string assignment statement (:=), you do not need to enclose a string 
literal in quotation marks (“”). String values are converted to uppercase 
automatically. Also, any leading and trailing spaces and:tabs are removed, and 
multiple spaces and tabs between characters are compressed to a single space. 


It is easier to use the assignment statement (=) to create symbols with string 
values because the assignment statement does not automatically convert letters 
to uppercase and remove extra spaces. Also, the assignment statement allows 
you to perform string operations in expressions. 


To prohibit uppercase conversion and to retain required space and tab characters 
in a string, place quotation marks around the string. To use quotation marks in 
a string, enclose the entire string within quotation marks and use a double set of 
quotation marks within the string. For example: 


$ TEST := "this is a ""test"" string" 
$ SHOW SYMBOL TEST 
TEST = "this is a "test" string" 


In this example, the spaces, lowercase letters, and quotation marks are preserved 
in the symbol definition. 
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To continue a symbol assignment on more than one line, use the hyphen (-)asa 
continuation character. For example: 


$ LONG STRING := THIS SYMBOL ASSIGNMENT IS A VERY LONG- 
_$ _SYMBOL STRING 


To assign a null string to a symbol by using the string assignment statement, do 
not specify a string. For example: 


$ NULL := 


Specify the string as a string literal, or as a symbol or lexical function that 
evaluates to a string literal. If you use symbols or lexical functions, place single 
quotation marks (‘’) around them to request symbol substitution. See the 
OpenVMS User’s Manual for more information on symbol substitution. 


You can also use the string assignment statement to define a foreign command. 
See the OpenVMS User’s Manual for more information about foreign commands. 


[offset,size] 

Specifies that a portion of a symbol value is to be overlaid with a replacement 
string. This form of the string assignment statement evaluates the value assigned 
to a symbol and then replaces the portion of the value (defined by the offset and 
size) with the replacement string. The brackets are required notation, and no 
spaces are allowed between the symbol name and the left bracket. 


The offset specifies the character position relative to the beginning of the symbol 
name’s string value at which replacement is to begin. Offset values start at 0. 


If the offset is greater than the offset of the last character in the string you are 
modifying, spaces are inserted between the end of the string and the offset where 
the replacement string is added. The maximum offset value you can specify is 
768. 


The size specifies the number of characters to replace. Size values start at 1. 


Specify the offset and size as integer expressions. See the OpenVMS User’s 
Manual for more information on integer expressions. The value of the size plus 
the offset must not exceed 769. 


replacement-string 

Specifies the string that is used to overwrite the string you are modifying. If the 
replacement string is shorter than the size argument, the replacement string 

is filled with blanks on the right until it equals the specified size. Then the 
replacement string overwrites the string assigned to the symbol name. If the 
replacement string is longer than the size argument, then the replacement string 
is truncated on the right to the specified size. | 


You can specify the replacement string as a string literal, or as a symbol or lexical 
function that evaluates to a string literal. If you use symbols or lexical functions, 
place single quotation marks (‘’) around them to request symbol substitution. 
For more information on symbol substitution, see the OpenVMS User’s Manual. 


Examples 


= (String Assignment) 


$ TIME := SHOW TIME 
$ TIME 
14-DEC-1995 11:55:44 


In this example, the symbol TIME is equated to the command string SHOW 
TIME. Because the symbol name appears as the first word in a command 
string, the command interpreter automatically substitutes it with its string 
value and executes the command SHOW TIME. 


$ STAT := SDBA1:[CRAMER]STAT 
$ STAT 


This example shows how to define STAT as a foreign command. The symbol 
STAT is equated to a string that begins with a dollar sign followed by a file 
specification. The command interpreter assumes that the file specification 

is that of an executable image, that is, a file with a file type of EXE. The 
symbol STAT in this example becomes a synonym for the following command: 


$ RUN DBA1: [CRAMER]STAT.EXE 


When you subsequently enter STAT, the command interpreter executes the 
image. 


A= "this is a big Space." 
SHOW SYMBOL A 

A= "this is a big space." 
B := ‘A’ 

SHOW SYMBOL B 

B = "THIS IS A BIG SPACE." 


$ 
$ 
$ 
$ 


This example compares the assignment and the string assignment 
statements. The symbol A is defined using the assignment statement, so 
lowercase letters and multiple spaces are retained. The symbol B is defined 
using the string assignment statement. Note that the single quotation marks 
(‘’) are required; otherwise, the symbol name B would have been equated to 
the literal string A. However, when symbol A’s value is assigned to symbol B, 
the letters are converted to uppercase and multiple spaces are compressed. 


$ FILE NAME := MYFILE 

$ FILE NAME[0,2]:= OL 

$ SHOW SYMBOL FILE NAME 
FILE NAME = "OLFILE" 


In this example, the substring expression in the assignment statement 
overlays the first 2 characters of the string assigned to the symbol FILE_ 
NAME with the letters OL. The offset of 0 requests that the overlay begin 
with the first character in the string, and the size specification of 2 indicates 
the number of characters to overlay. 


$ FILE NAME := MYFILE 
$ FILE TYPE := .TST 
$ FILE NAME[FSLENGTH(FILE NAME),4] := ‘FILE TYPE’ 


$ SHOW SYMBOL FILE NAME 
FILE NAME = "MYFILE.TST" 


In this example, the symbol name FILE_NAME is equated to the string 
MYFILE and the symbol name FILE_TYPE is equated to the string .TST. The 
third assignment statement uses the lexical function FSLENGTH to define 
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the offset value where the overlay is to begin. The symbol name FILE_TYPE 
is used to refer to the replacement string (.TST). Note that you must use 
single quotation marks (‘’) to request symbol substitution. 


~The FSLENGTH lexical function returns the length of the string equated to 


the symbol FILE_NAME; this length is used as the offset. The expression 
requests that 4 characters of the string currently equated to the symbol 
FILE_TYPE be placed at the end of the string currently equated to FILE_ 
NAME. The resultant value of the symbol FILE_NAME is MYFILE.TST. 


@ (Execute Procedure) 


@ (Execute Procedure) 


Format 


Parameters 


Executes a command procedure or requests the command interpreter to read 
subsequent command input from a specific file or device. 


@ _ filespec [parameter{,...]] 


filespec 

Specifies either the input device or the file for the preceding command, or the 
command procedure to be executed. The default file type is COM. The asterisk 
(*) and the percent sign (%) wildcard characters are not allowed in the file 


specification. 


parameter{,...] 

Specifies from one to eight optional parameters to pass to the command 
procedure. The symbols (P1, P2, ... P8) are assigned character string values 

in the order of entry. The symbols are local to the specified command procedure. 
Separate each parameter with one or more blanks. Use two consecutive quotation 
marks ("") to specify a null parameter. You can specify a parameter with a 
character string value containing alphanumeric or special characters, with the 
following restrictions: 


e The command interpreter converts alphabetic characters to uppercase and 
uses blanks to delimit each parameter. To pass a parameter that contains 
embedded blanks or literal lowercase letters, place the parameter in quotation 
marks. 


e Ifthe first parameter begins with a slash (/), you must enclose the parameter 
in quotation marks (“ ”). 


e To pass a parameter that contains literal quotation marks and spaces, enclose 
the entire string in quotation marks and use two consecutive quotation marks 
within the string. For example, the command procedure TEST.COM contains 
the following line: 


$ WRITE SYSSOUTPUT Pl 
Enter the following at the DCL prompt ($): 
$ @TEST "Never say ""quit""" 


When the procedure TEST.COM executes, the parameter P1 is equated to the 
following string: 


Never say "quit" 


If a string contains quotation marks and does not contain spaces, the 
quotation marks are preserved in the string and the letters within the 
quotation marks remain in lowercase. For example, enter the following at the 
DCL prompt: 


$ @TEST abc"def"ghi 
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When the procedure TEST.COM executes, the parameter P1 is equated to the 
following string: 


ABC"def"GHI 


To use a symbol as a parameter, enclose the symbol in single quotation marks 
(‘’) to force symbol substitution. For example: 


$ NAME = "JOHNSON" 
$ @INFO ‘NAME’ 


The single quotation marks cause the value “JOHNSON?” to be substituted for 
the symbol NAME. Therefore, the parameter “JOHNSON?” is a as P1 to 
INFO.COM. | 


Use the @ command to execute a command procedure that contains the following: 


_® DCL command lines or data, or both 


¢ Qualifiers or parameters, or both, for a specific command line 


To execute a command procedure containing commands or data, or both, place the 
@ command at the beginning of a command line and then specify the name of the 
command procedure file. The command procedure can contain DCL commands 
and input data for a command or program that is currently executing. All DCL 
commands in a command procedure must begin with a dollar sign ($). Ifa 
command is continued with a hyphen (-), the subsequent lines must not begin 
with a dollar sign. 


Any line in a command procedure that does not contain a dollar sign in the first 
character position (and is not a continuation line) is treated as input data for the 
command or program that is currently executing. The DECK command allows 
you to specify that data contains dollar signs in record position one. 


A command procedure can also contain the @ command to execute another 
command procedure. The maximum command level you can achieve by 
nesting command procedures is 16, including the top-level command procedure. 
Command procedures can also be queued for processing as batch jobs, either 
by using the SUBMIT command or by placing a deck of cards containing the 
command procedure in the system card reader. 


To execute a command procedure that contains qualifiers or parameters, or 
both, for a specific command line, place the @ command where the qualifiers or 
parameters normally would be in the command line. Then specify the name of 
the command procedure file containing the qualifiers or parameters. 


If the command procedure file begins with parameters for the command, the @ 
command must be preceded by a space. For example: 


$ CREATE TEST.COM 
TIME 


$ SHOW @TEST 
14-DEC-1994 17:20:26 


If the file begins with qualifiers for the command, do not precede the @ command 
with a space. For example: 


$ CREATE TEST 2.COM 
/SIZE 


Qualifier 


_ Examples 


@ (Execute Procedure) 


[wiz] 
$ DIR@TEST_2 


Directory WORKS: [SCHEDULE] 


JANUARY . TXT; 8 14-DEC-1994 15:47:45.57 
FEBRUARY. TXT; 7 14-DEC-1994 15:43:16.20 


MARCH. TXT; 6 14-DEC-1994 11:11:45.74 


total of 11° files. 


If the file contains parameters or qualifiers, or both, do not begin the lines in 
the file with dollar signs. Any additional data on the command line following 
@filespec is treated as parameters for the procedure. 


/OUTPUT=filespec 

Specifies the name of the file to which the command procedure output is written. 
By default, the output is written to the current SYS$OUTPUT device. The 
default output file type is .LIS. The asterisk (*) and the percent sign (%) 
wildcard characters are not allowed in the output file specification. System 
responses and error messages are written to SYS$COMMAND as well as to 

the specified file. The /OUTPUT qualifier must immediately follow the file 
specification of the command procedure; otherwise, the qualifier is interpreted as 
a parameter to pass to the command procedure. 


You can also redefine SYS$OUTPUT to redirect the output from a command 
procedure. If you place the following command as the first line in a command 
procedure, output will be directed to the file you specify: 


$ DEFINE SYS$OUTPUT filespec 


When the procedure exits, SYS$OUTPUT will be restored to its original 
equivalence string. This produces the same result as using the /OUTPUT 
qualifier when you execute the command procedure. 


1. $ CREATE DOFOR.COM 
$ ON WARNING THEN EXIT 
$ IF P1.EQS."" THEN INQUIRE Pl FILE 
$ FORTRAN/LIST 'P1! 
$ LINK 'P1’ 
$ RUN 'P1! 
$ PRINT 'P1’ 


$ @DOFOR AVERAGE 


This example shows a command procedure, named DOFOR.COM, that 
executes the FORTRAN, LINK, and RUN commands to compile, link, and 


execute a program. The ON command requests that the procedure not 
continue if any of the commands result in warnings or errors. 


When you execute DOFOR.COM, you can pass the file specification of the 
FORTRAN program as the parameter P1. If you do not specify a value for Pl 

when you execute the procedure, the INQUIRE command issues a prompting 

message to the terminal and equates what you enter with the symbol P1. In 
_ this example, the file name AVERAGE is assigned to P1. The file type is not 
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included because the commands FORTRAN, LINK, RUN, and PRINT provide 
default file types. 


$ @MASTER/OUTPUT=MASTER. LOG 


This command executes a procedure named MASTER.COM; all output is 
written to the file MASTER.LOG. 


$ CREATE FILES.COM 
*.FOR, *.OBJ 


$ DIRECTORY @FILES 


This example shows a command procedure, FILES.COM, that contains 
parameters for a DCL command line. You can execute this procedure after 
the DIRECTORY command to get a listing of all Fortran source and object 
files in your current default directory. 


$ CREATE QUALIFIERS .COM 
/DEBUG/SYMBOL TABLE/MAP/FULL/CROSS REFERENCE 


$ LINK SYNAPSE@QUALIFIERS 


This example shows a command procedure, QUALIFIERS.COM, that contains 
qualifiers for the LINK command. When you enter the LINK command, 
specify the command procedure immediately after the file specification of the 
file you are linking. Do not type a space between the file specification and the 
@ command. 


$ CREATE SUBPROCES.COM 
$ RUN ‘Pl’ - 
/BUFFER LIMIT=1024 - 
/FILE_LIMIT=4 - 
/PAGE FILES=256 - 
/QUEVE_LIMIT=2 - 
/SUBPROCESS LIMIT=2 - 
'p2' 'p3! ‘pd! ‘ps5: 'p6! 'p7' ‘pg: 
[ewi2] 
$ @SUBPROCES LIBRA /PROCESS NAME=LIBRA 


This example shows a command procedure named SUBPROCES.COM. This 
procedure issues the RUN command to create a subprocess to execute an 
image and also contains qualifiers defining quotas for subprocess creation. 
The name of the image to be run is passed as the parameter P1. Parameters 
P2 to P8 can be used to specify additional qualifiers. 


In this example, the file name LIBRA is equated to P1; it is the name of an 
image to execute in the subprocess. The qualifier /PROCESS_NAME=LIBRA 
is equated to P2; it is an additional qualifier for the RUN command. 


$ CREATE EDOC.COM 
$ ASSIGN SYSSCOMMAND: SYSSINPUT 


S NEXT: 

$ INQUIRE NAME "File name" 
$ IF NAME.EQS."" THEN EXIT 
$ EDIT/TPU ‘NAME’ .DOC 

$ GOTO NEXT 


@ (Execute Procedure) 


$ @EDOC 

This procedure, named EDOC.COM, invokes the EVE editor. When an edit 
session is terminated, the procedure loops to the label NEXT. Each time 
through the loop, the procedure requests another file name for the editor and 
supplies the default file type .DOC. When a null line is entered in response to 
the INQUIRE command, the procedure terminates with the EXIT command. 


The ASSIGN command changes the equivalence name of SYS$INPUT for the 
duration of the procedure. This change allows the EVE editor to read input 
data from the terminal, rather than from the command procedure file (the 
default input data stream if SYS$INPUT had not been changed). When the 
command procedure exits, SYS$INPUT is reassigned to its original value. 
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ACCOUNTING 


Runs the Accounting utility, which produces reports of resource use. For 
a complete description of the Accounting utility, see the OpenVMS System 
Management Utilities Reference Manual. 


Format 
ACCOUNTING [filespec{,...]] 
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Format 


Parameters 


Qualifiers 


Provides your process with exclusive access to a device until you deallocate the 
device or terminate your process. Optionally associates a logical name with the 
device. 


Requires read (R), write (W), or control access. 


ALLOCATE device-name[:][,...] [logical-name[:]] 


device-name[:][,...] 

Specifies the name of a physical device or a logical name that translates to the 
name of a physical device. The device name can be generic: if no controller or 
unit number is specified, any device that satisfies the specified part of the name 
is allocated. If more than one device is specified, the first available device is 
allocated. . 


logical-name[:] 

Specifies a string of 1 to 255 alphanumeric characters. Enclose the string in 
single quotation marks (‘’) if it contains blanks. Trailing colons (:) are not 
used. The name becomes a process logical name with the device name as the 
equivalence name. The logical name remains defined until it is explicitly deleted 
or your process terminates. 


/GENERIC 

/NOGENERIC (default) 

Indicates that the first parameter is a device type rather than a device name. 
Example device types are: RX50, RD52, TK50, RC25, RCF25, and RLO2. The 
first free, nonallocated device of the specified name and type is allocated. 


The /LNO]JGENERIC qualifier is placed before the device-name parameter in the 
ALLOCATE command line. For example, you can allocate an RKO7 device by 
entering the following command at the DCL prompt ($): 


$ ALLOCATE/GENERIC RK07 DISK 


The following table shows some device types that you can specify with the 
/GENERIC qualifier. To see what devices are available, refer to your SPD for the 
OpenVMS version they are currently using, 


Devices by Classification 


Disk Devices 


EF51 EF58 ESE20 ESE58 EZ31 
EZ58 HSZ10 HSZ40 ML11 RA60 
RA70 RA80 RA90 RAH72 RB02 
RB80 RC25 RCF25 RD26 RD54 
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Devices by Classification 


Disk Devices 


RF30 RFH73 RKO7 RL02 RM80 
RP07 RX18 RX50 RZO1 RZFO1 


Compact Disk Devices 


RRD40 RRD40S RRD42 RRD43 RRD44 
RRD50 RV20 RV60 RV80 RW504 
RW510 RW514 RW516 RWZO01 RW2Z21 
RWZ31 _ RWZ2Z51 — RWZ52 RW2Z53 RW2Z54 


Tape Devices 


TA78 TA90 TA90E TA91 TAD85 
TAPE TD34 TD44 TE16 TF30 

TF70 TK50 TK60 TK70 TKZ60 
TL810 TLZ7 | TM32 TS11 TSZ08 


TU45 TU81 TZ30 TZ895 TZXO 


/LOG (default) 

INOLOG 

Displays a message indicating the name of the device allocated. If the operation 
specifies a logical name that is currently assigned to another device, then the 
superseded value is displayed. 


1. 


$ ALLOCATE DMB2: 
tDCL-I-ALLOC, _DMB2: allocated 


The ALLOCATE command in this example requests the allocation of a specific 
RKO6/RKO7 disk drive, that is, unit 2 on controller B. The system response 
indicates that the device was allocated successfully. 


$ ALLOCATE MT,MF: TAPE: 
tDCL-I-ALLOC, MTB2: allocated 


e 


$ SHOW LOGICAL TAPE: 

TAPE: = MTB2: (process) 
$ DEALLOCATE TAPE: 

$ DEASSIGN TAPE: 


The ALLOCATE command in this example requests the allocation of a tape 
device whose name begins with MT or MF and assigns it the logical name 
TAPE. The ALLOCATE command locates an available tape device whose 
name begins with MT, and responds with the name of the device allocated. (If 
no tape device beginning with MT had been found, the ALLOCATE command 
would have searched for a device beginning with MF.) Subsequent references 
to the device TAPE in user programs or command strings are translated to 
the device name MTB2. 


ALLOCATE 


When the tape device is no longer needed, the DEALLOCATE command 
deallocates it and the DEASSIGN command deletes the logical name. Note 
that the logical name TAPE was specified with a colon on the ALLOCATE 
command, but that the logical name table entry does not have a colon. 


$ ALLOCATE/GENERIC RL02 WORK 
$DCL-I-ALLOC, DLA1: allocated 
%DCL-I-SUPERSEDE, previous value of WORK has been superseded 


The ALLOCATE command in this example requests the allocation of any 
RLO2 disk device and assigns the logical name WORK to the device. The 
completion message identifies the allocated device and indicates that the 
assignment of the logical name WORK supersedes a previous assignment of 
that name. 


$ ALLOCATE STAPE1 

$DCL-I-ALLOC, _MUAQ: allocated 

The ALLOCATE command in this example allocates the tape device MUAO, 
which is associated with the logical name $TAPE1. 

$ ALLOCATE /GENERIC RX50 ACCOUNTS 


The ALLOCATE command in this example allocates the first free floppy disk 
drive and makes its name equivalent to the process logical name ACCOUNTS. 
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ANALYZE/AUDIT 


ANALYZE/AUDIT 


Invokes the Audit Analysis utility, which selectively extracts and displays 
information from security audit log files or security archive files. For a complete 
description of the Audit Analysis utility, see the OpenVMS System Management 
Utilities Reference Manual. 

Format 


ANALYZE/AUDIT __ [filespec] 
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ANALYZE/CRASH_DUMP 


Invokes the System Dump Analyzer utility, which analyzes a system dump file. 
The /CRASH_DUMP qualifier is required. 


For a complete description of the System Dump Analyzer utility on Alpha, see 
the OpenVMS Alpha System Dump Analyzer Utility Manual. For a complete 
description of the System Dump Analyzer utility on VAX, see the OpenVMS VAX 
System Dump Analyzer Utility Manual. 


Format 
ANALYZE/CRASH_DUMP _filespec 
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ANALYZE/DISK_STRUCTURE 


Invokes the Analyze/Disk_Structure utility, which does the following: 

e Checks the readability and validity of Files—11 On-Disk Structure Level 1 and 
Files—11 On-Disk Structure Level 2 disk volumes. 

e Reports errors and inconsistencies. 


The /DISK_STRUCTURE qualifier is required. For a complete description of the 
Analyze/Disk_Structure utility, see the OpenVMS System Management Utilities 


Reference Manual. 


Format 
ANALYZE/DISK_STRUCTURE  device-namef[:] 
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ANALYZE/ERROR_LOG 


Format 


Invokes the Errorlog Report Formatter, which selectively reports the contents 
of an error log file. The /ERROR_LOG qualifier is required. For a complete 
description of the Error Log utility, see the OpenVMS ay aeM Management 
Utilities Reference Manual. 


ANALYZE/ERROR_LOG [filespecf,...]] 
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ANALYZE/IMAGE 


Format 


Parameter 


Description 


Analyzes the contents of an executable image file or a shareable image file on 
Alpha, VAX, and translated VAX images, and checks for obvious errors in the 
image file. The /IMAGE qualifier is required. For general information about 
image files, see the description of the linker in the OpenVMS Linker Utility 
Manual. (Use the ANALYZE/OBJECT command to analyze the contents of an 
object file.) 


Note 


The OpenVMS VAX Version 6.1 and 6.2 ANALYZE/IMAGE command 
cannot analyze an OpenVMS Alpha image. 


ANALYZE/IMAGE _filespecf,...] 


filespec[,...] 

Specifies the name of one or more image files that you want analyzed. You must 
specify at least one file name. If you specify more than one file, separate the file 
specifications with either commas (,) or plus signs (+). The default file type is 
EXE, 


The asterisk (*) and percent sign (%) wildcard characters are allowed in the file 
specification. 


The ANALYZE/AIMMAGE command provides a description of the components of an 
executable image file or shareable image file. It also verifies that the structure 
of the major parts of the image file is correct. However, the ANALYZE/IMAGE 
command cannot ensure that program execution is error free. 


If errors are found, the first error of the worst severity is returned. For example, 
if a warning (A) and two errors (B and C) are found, the first error (B) is returned 
as the image exit status. The image exit status is placed in the DCL symbol 
$STATUS at image exit. 


. The ANALYZE/IMAGE command distinguishes Alpha system image files from 
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VAX system image files by examining the extended image header (EIHD). 
The ANALYZE/IMAGE command provides the following information: 
e Image type—Identifies whether the image is executable or shareable. 


e Image transfer addresses—Identify the addresses to which control is passed 
at image execution time. 


e Image version—Identifies the revision level (major ID and minor ID) of the 
image. 


¢ Location and size of the image’s symbol vector (Alpha only) 


Qualifiers 


ANALYZE/IMAGE 


¢ Location of the debugger symbol table (DST)—Identifies the location of the 
DST in the image file. DST information is present only in executable images 
that have been linked with the /DEBUG or the /TRACEBACK command 
qualifier. 


¢ Location of the global symbol table (GST)—Identifies the location of the GST 
in the image file. GST information is present only in shareable image files. 


¢ Patch information—Indicates whether the image has been patched (changed 
without having been recompiled or reassembled and relinked). If a patch is 
present, the actual patch code can be displayed. 


¢ Image section descriptors (ISD)—Identify portions of the image binary 
contents that are grouped in VMScluster systems according to their 
attributes. An ISD contains information that the image activator needs 
when it initializes the address space for an image. For example, an ISD tells 
whether the ISD is shareable, whether it is readable or writable, whether it 
is based or position independent, and how much memory should be allocated. 


e Fixup vectors—Contain information that the image activator needs to ensure 
the position independence of shareable image references. 


e System version categories—For an image that is linked against the executive 
(the system shareable image on Alpha or the system symbol table on VAX), 
displays both the values of the system version categories for which the image 
was linked originally and the values for the system that is currently running. 
You can use these values to identify changes in the system since the image 
was linked last. 


The ANALYZE/IMAGE command has command qualifiers and positional 
qualifiers. By default, if you do not specify any positional qualifiers (for example, 
/GST or /HEADER), the entire image is analyzed. If you do specify a positional 
qualifier, the analysis excludes all other positional qualifiers except the /HEADER 
qualifier (which is always enabled) and any qualifier that you request explicitly. 


/FIXUP_SECTION 
Positional qualifier. 


Specifies that the analysis should include all information in the fixup section of 
the image. 


If you specify the /FIXUP_SECTION qualifier after the ANALYZE/IMAGE 
command, the fixup section of each image file in the parameter list is analyzed. 


If you specify the /FIXUP_SECTION qualifier after a file specification, only the 
information in the fixup section of that image file is analyzed. 
IGST 


Positional qualifier. 


Specifies that the analysis should include all global symbol table records. This 
qualifier is valid only for shareable images. 


If you specify the /GST qualifier after the ANALYZE/IMAGE command, the global 
symbol table records of each image file in the parameter list are analyzed. 


If you specify the /GST qualifier after a file Spyencenon, only the global symbol 
table records of that file are analyzed. 
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ANALYZE/IMAGE 


Examples 
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/HEADER 
Positional qualifier. 


Specifies that the analysis should include all header items and image section 
descriptions. The image header items are always analyzed. 


ANTERACTIVE 

/NOINTERACTIVE (default) 

Specifies whether the analysis is interactive. In interactive mode, as each item is 
analyzed, the results are displayed on the screen and you are asked whether you 
want to continue. 


/OUTPUT=filespec 

Identifies the output file for storing the results of the image analysis. The 
asterisk (*) and the percent sign (%) wildcard characters are not allowed in the 
file specification. If you specify a file type and omit the file name, the default file 
name ANALYZE is used. The default file type is .ANL. If you omit the qualifier, 
the results are output to the current SYS$OUTPUT device. 


/PATCH_TEXT 
Positional qualifier. 


Specifies that the analysis include all patch text records. If you specify the 
/PATCH_TEXT qualifier after the ANALYZE/IMAGE command, the patch text 
records of each image file in the parameter list are analyzed. 


If you specify the /PATCH_TEXT qualifier after a file specification, only the patch 
text records of that file are analyzed. 


1. $ ANALYZE/IMAGE LINEDT 


The ANALYZE/IMAGE command in this example produces a description and 
an error analysis of the image LINEDT.EXE. Output is sent to the current 
SYS$OUTPUT device. By default, the entire image is analyzed. 


2. $ ANALYZE/IMAGE/OUTPUT=LIALPHEX/FIXUP_SECTION/PATCH TEXT LINEDT, ALPRIN 


The ANALYZE/IMAGE command in this example produces a description 
and an error analysis of the fixup sections and patch text records of 
LINEDT.EXE and ALPRIN.EXE in file LIALPHEX.ANL. Output is sent 
to the file LIALPHEX.ANL. 


ANALYZE/MEDIA 


ANALYZE/MEDIA 


Invokes the Bad Block Locator utility, which analyzes block-addressable devices 
and records the location of blocks that cannot reliably store data. For a complete 


description of the Bad Block Locator utility, see the OpenVMS Bad Block Locator 
Utility Manual. 


Format 
ANALYZE/MEDIA device 
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ANALYZE/OBJECT 


Format 


Parameter 


Description 
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Analyzes the contents of an object file. Also, checks for any obvious errors. The 
/OBJECT qualifier is required. (Use the ANALYZE/IMAGE command to analyze 
the contents of an image file.) 


ANALYZE/OBJECT _filespec[,...] 


filespec{,...] 

Specifies the object files or object module libraries you want analyzed (the default 
file type is .OBJ). Use commas (,) or plus signs (+) to separate file specifications. 
The asterisk (*) and the percent sign (%) wildcard characters are allowed in the 
file specification. ; 


The ANALYZE/OBJECT command describes the contents of one or more object 
modules contained in one or more files. It also performs a partial error analysis. 
This analysis determines whether all records in an object module conform in 
content, format, and sequence to the specifications of the Alpha or VAX Object 
Language. 


The ANALYZE/OBJECT command automatically distinguishes Alpha objects 
from VAX objects by examining the format of the extended object modules header 
(EOMH). 


ANALYZE/OBJECT is intended primarily for programmers of compilers, 
debuggers, or other software involving the operating system’s object modules. 

It checks that the object language records generated by the object modules are 
acceptable to the Linker utility, and it identifies certain errors in the file. It also 
provides a description of the records in the object file or object module library. 
For more information on the linker and on the Alpha and VAX object languages, 
refer to the OpenVMS Linker Utility Manual. 


The ANALYZE/OBJECT command analyzes the object modules in order, record 
by record, from the first to the last record in the object module. Fields in each 
record are analyzed in order from the first to the last field in the record. After 
the object module is analyzed, you should compare the content and format of each 
type of record to the required content and format of that record as described by 
the OpenVMS Alpha or OpenVMS VAX Object Language. This comparison is 
particularly important if the analysis output contains a diagnostic message. 


Linking an object module differs from analyzing an object module. Object 

language commands are not executed in an analysis, but they are executed in 
a linking operation. As a result, even if the analysis is error free, the linking 
operation may not be. In particular, the analysis does not check the following: 


e That data arguments in TIR commands are in the correct format. 
¢ That “Store Data” TIR commands are storing within legal address limits. 


Therefore, as a final check, you should still link an object module whose analysis 
is error free. 


Qualifiers 


ANALYZE/OBJECT 


If an error is found, however, the first error of the worst severity that is 
discovered is returned. For example, if a warning (A) and two errors (B and 
C) are signaled, then the first error (B) is returned as the image exit status, 
which is placed in the DCL symbol $STATUS at image exit. 


ANALYZE/OBJECT uses positional qualifiers; that is, qualifiers whose function 
depends on their position in the command line. When a positional qualifier 
precedes all of the input files in a command line, it affects all input files. For 
example, the following command line requests that the analysis include the global 
symbol directory records in files A, B, and C: 


$ ANALYZE/OBJECT/GSD A,B,C 


Conversely, when a positional qualifier is associated with only one file in the 
parameter list, only that file is affected. For example, the following command line 
requests that the analysis include the global symbol directory records in file B 
only: 


$ ANALYZE/OBJECT A,B/GSD,C 


Typically, all records in an object module are analyzed. However, when the /DBG, 
/KOM, /GSD, /LNK, /MHD, /TBT, or /TIR qualifier is specified, only the record 
types indicated by the qualifiers are analyzed. All other record types are ignored. 


By default, the analysis includes all record types unless you explicitly request a 
limited analysis using appropriate qualifiers. 


Note 


End-of-module (EOM) records and module header (MHD) records are 
always analyzed, no matter which qualifiers you specify. 


/DBG 
Positional qualifier. 


Specifies that the analysis should include all debugger information records. If you 
want the analysis to include debugger information for all files in the parameter 
list, insert the /DBG qualifier immediately following the /OBJECT qualifier. If 
you want the analysis to include debugger information selectively, insert the 
/DBG qualifier immediately following each of the selected file specifications. 


/EOM 
Positional qualifier. 


Specifies that the analysis should be limited to MHD records, EOM records, 
and records explicitly specified by the command. If you want this to apply to all 
files in the parameter list, insert the /EOM qualifier immediately following the 
/OBJECT qualifier. 


To make the /EOM qualifier applicable selectively, insert it immediately following 
each of the selected file specifications. 


Note 


End-of-module records can be EOM or EOMW records. See the OpenVMS 
Linker Utility Manual for more information. 
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ANALYZE/OBJECT 


DCLI-28 


/GSD 
Positional qualifier. 


Specifies that the analysis should include all global symbol directory (GSD) 
records. 


If you want the analysis to include GSD records for each file in the parameter 
list, specify the /GSD qualifier immediately following the /OBJECT qualifier. 


If you want the analysis to include GSD records selectively, insert the /GSD 
qualifier immediately following each of the selected file specifications. 


ANCLUDE[=(module{,...])] 

When the specified file is an object module library, use this qualifier to list 
selected object modules within the library for analysis. If you omit the list or 
specify an asterisk (*), all modules are analyzed. If you specify only one module, 
you can omit the parentheses. 


ANTERACTIVE 

/NOINTERACTIVE (default) 

Controls whether the analysis occurs interactively. In interactive mode, as each 
record is analyzed, the results are displayed on the screen, and you are asked 
whether you want to continue. 


/LNK 
Positional qualifier. 


Specifies that the analysis should include all link option specification (LNK) 
records. 


If you want the analysis to include LNK records for each file in the parameter 
list, specify the /LNK qualifier immediately following the /OBJECT qualifier. 


If you want the analysis to include LNK records selectively, insert the /LNK 
qualifier immediately following each of the selected file specifications. 


/MHD 
Positional qualifier. 


Specifies that the analysis should be limited to MHD records, EOM records, and 
records explicitly specified by the command. If you want this analysis to apply 
to all files in the parameter list, insert the /MHD qualifier immediately following 
the /OBJECT qualifier. 


To make the /MHD qualifier applicable selectively, insert immediately following 
each of the selected file specifications. 


/OUTPUT[=filespec] 

Directs the output of the object analysis (the default is SYS$OUTPUT). If you 
specify a file type and omit the file name, the default file name ANALYZE is used. 
The default file type is ANL. 


The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


/TBT 
Positional qualifier. 


Specifies that the analysis should include all module traceback (TBT) records. 


Examples 


ANALYZE/OBJECT 


If you want the analysis to include TBT records for each file in the parameter list, 
specify the /TBT qualifier immediately following the /OBJECT qualifier. 


If you want the analysis to include TBT records selectively, insert the /TBT 
qualifier immediately following each of the selected file specifications. 


/TIR 
Positional qualifier. 


Specifies that the analysis should include all text information and relocation 
(TIR) records. 


If you want the analysis to include TIR records for each file in the parameter list, 
specify the /TIR qualifier immediately following the /OBJECT qualifier. 


If you want the analysis to include TIR records selectively, insert the /TIR 
qualifier immediately following the selected file specifications. 


1. $ ANALYZE/OBJECT/INTERACTIVE LINEDT 


In this example, the ANALYZE/OBJECT command produces a description and 
a partial error analysis of the object file LINEDT.OBJ. By default, all types of 
records are analyzed. Output is to the terminal, because the /INTERACTIVE 
qualifier has been used. As each item is analyzed, the utility displays the 
results on the screen and asks if you want to continue. 


2. $ ANALYZE/OBJECT/OUTPUT=LIOBJ/DBG LINEDT 


In this example, the ANALYZE/OBJECT command analyzes only the 
debugger information records of the file LINEDT.OBJ. Output is to the 
file LIOBJ.ANL. 
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ANALYZE/PROCESS_DUMP 


Format 


Parameter 


Description 
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Invokes the OpenVMS Debugger to analyze a process dump file that was created 
when an image failed during execution. (Use the /DUMP qualifier with the RUN 
or the SET PROCESS command to generate a dump file.) 


The ANALYZE/PROCESS_DUMP command can display a process dump file 

for either an Alpha or VAX image. For a complete description of the debugger 
(including information about the DEBUG command), see the OpenVMS Debugger 
Manual. 


Requires read (R) access to the dump file. 
ANALYZE/PROCESS_DUMP_ dump-file 


dump-file 
Specifies the dump file to be analyzed with the debugger. 


The ANALYZE/PROCESS_DUMP command examines the dump file of an image 
that failed during execution. The OpenVMS Debugger is invoked automatically. 
To cause a dump file to be created for a process, you must use the /DUMP 
qualifier with the RUN command when invoking the image, or you must use the 
SET PROCESS/DUMP command before invoking the image. 


Analysis of a process dump on a system other than on the system where the 
dump was generated is not recommended. Different configurations can cause 
the process executing the ANALYZE/PROCESS_DUMP command to fail to 
successfully load the dumped image. For example, if the systems have different 
versions of the operating system, the analysis may work, but it is not guaranteed. 


Other restrictions include the configuration of the control regions (P1 space), 
the process running at the time of the dump, and the process performing the 
ANALYZE/PROCESS_DUMP command. The location of the base of the user 
stack for each process, which depends upon the size of Pl space, determines 
whether the processes are compatible. The size of P1 space for the process 
analyzing the dump must be less than the size of P1 space for the process which 
created the dump. If you are analyzing the dump on a different system, but with 
the same version of the operating system, you can decrease the size of P1 space 
by modifying one or more of the system parameters that affect the size of P1 
space. You can modify the system parameter IMGIOCNT dynamically. 


On Alpha, in some cases, the OpenVMS Debugger is incapable of analyzing 

the dumped image. For example, when the dumped image’s PC is set to an 
invalid address or when the dumped image’s stack is corrupted by a bad process 
descriptor, you must use the Delta Debugger (DELTA) to analyze the dump. To 
use DELTA as the debugger, the image SYS$LIBRARY:DELTA must be installed 
by invoking the Install utility. For complete information on the Install utility, see 
the OpenVMS System Management Utilities Reference Manual.¢ 


Qualifiers 


Examples 


<i> 


ANALYZE/PROCESS_ DUMP 


/FULL 
Displays all known information about the failing process. 


AMAGE=image-name 

/NOIMAGE 

Specifies the image whose symbols are to be used in analyzing the dump. If you 
use the /NOIMAGE qualifier, no symbols are taken from any image. By default, 
symbols are taken from the image with the same name as the image that was 
running at the time of the dump. 


ANTERACTIVE 

/NOINTERACTIVE (default) 

Causes the display of information to pause when your terminal screen is filled. 
Press the Return key to display additional information. By default, the display is 
continuous. 


/MISCELLANEOUS 

Displays process information and registers at the time of the dump. Refer to 
the $GETJPI system service for further explanation of the process information 
displayed. 


/OUTPUT=filespec 

Writes the information to the specified file. By default, the information is written 
to the current SYS$OUTPUT device. The asterisk (*) and the percent sign (%) 
wildcard characters are not allowed in the file specification. 


/RELOCATION 

Displays the addresses to which data structures saved in the dump are mapped in 
PO space. (Examples of such data structures are the stacks.) The data structures 
in the dump must be mapped into PO space so that the debugger can use those 
data structures in P1 space. 


1. $ ANALYZE/PROCESS/FULL ZIPLIST 


00018292 R1 = 8013DE20 R2 


= 7FFE6A40 R3 = 7FFE6A98 
R4 = 8013DE20 R5 = 00000000 R6 


7FFE7B9A R7 = 0000F000 


00000000 R9 = 00000000 R10 = 00000000 R11 = 00000000 
SP = 7FFAEF44 AP = 7FFAEF48 FP 7FFAEF 84 

FREE PO VA 00001600 FREE Pl VA 7FFAC600 

Active ASTs 00 Enabled ASTs OF 

Current Privileges FFFFFF80 1010C100 

Event Flags 00000000 £0000000 

Buffered I/O count/limit 6/6 

Direct I/O count/limit 6/6 


File count/limit 27/30 

Process count/limit 0/0 

Timer queue count/limit 10/10 

AST count/limit 6/6 

Enqueue count/limit 30/30 

Buffered I/0 total 7 Direct I/O total 18 
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Link Date 27-DEC-1994 15:02:00.48 Patch Date 17-NOV-1994 00:01:53.71 
ECO Level 0030008C 00540040 00000000 34303230 
Kernel stack 00000000 pages at 00000000 moved to 00000000 
Exec stack 00000000 pages at 00000000 moved to 00000000 
- Vector page 00000001 page at 7FFEFE00 moved to 00001600 
PIO (RMS) area 00000005 pages at 7FFE1200 moved to 00001800 
Image activator context 00000001 page at 7FFE3400 moved to 00002200 
User writable context 0000000A pages at 7FFE1C00 moved to 00002400 
Creating a subprocess 
VAX DEBUG Version 5.4 
DBG> 


This example shows the output of the ANALYZE/PROCESS command when 
used with the /FULL qualifier on a VAX system. The file specified, ZIPLIST, 
contains the dump of a process that encountered a fatal error. The DBG> 
prompt indicates that the debugger is ready to accept commands. ¢ 


| Alpha | 2. § ANALYZE/PROCESS/FULL ARITH.DMP 


RO = 000000000000000F R1 = 0000000000000001 R2 = 0000000000010000 
R3 = 000000007FF41E14 R4 = Q00000007FFBF80C R5 = 000000007FFBF91C 
R6 = 000000007FFA0D34 R7 = 000000007FFA0D34 R8 = 000000007FFA05F8 
RI = 000000007FFA0800 R10 = 000000007FFA1380 R11 = 000000007FFBE3E0 
R12 = 0000000000000004 R13 = FFFFFFFF84EF3730 R14 = 0000000000000000 
R15 = 0000000000000000 R16 = 00000000002D4EC8 R17 = 0000000100000000 
R18 = 00000000002D4EAE R19 = 0000000000000000 R20 = 0000000000000000 
R21 = 0000000000000000 R22 = 002D559100000000 R23 = 00000000002D5591 
R24 = 002D559100000000 R25 = 0000000000000003 R26 = 0000000000020040 
R27 = 0000000000032AA0 R28 = 0000000000052DA0 AP = 000000007FE6F6F0 
FP = 000000007FE6FA20 SP = 000000007FE6FA20 PC = 0000000000020048 


FREE PO VA 002F6000 FREE Pl VA 7FE68000 
Active ASTs 00 Enabled ASTs OF 

Current Privileges 00000000 00108000 
Event Flags 00000000 £0000000 

Buffered I/0 count/limit 100/100 

Direct I/O count/limit 100/100 


File count/limit 98/100 
Process count/limit 0/0 
Timer queue count/limit 10/10 
AST count/limit 98/100 
Enqueue count/limit 600/600 


Buffered I/O total 118 Direct I/O total 37 
Link Date 14-DEC-1994 13:06:06.72 


Kernel stack 00000000 pagelets at 00000000 moved to 00000000 

Exec stack 00000000 pagelets at 00000000 moved to 00000000 

Vector page 00000002 pagelet at 7FFF0000 moved to 002F6000 

PIO (RMS) area 00000000 pagelets at 00000000 moved to 00000000 

Image activator context 00000001 pagelet at 7FFDOE00 moved to 002F8000 
User writeable context 00000008 pagelets at 7FFC0000 moved to 002FA000 


Condition signalled to take dump: 

tSYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000000, 
-Fmask=00000001, summary=04, PC=00020048, PS=0000001B 
-SYSTEM-F-FLTDIV, arithmetic trap, floating/decimal divide by zero 
-at PC=00020048, PS=0000001B 


OpenVMS Alpha DEBUG Version T1.0-FT4 
%DEBUG-I-NOLOCALS, image does not contain local symbols 
%DEBUG-I-NOGLOBALS, some or all global symbols not accessible 
%DEBUG-I-NOUNIVERSALS, shareable image contains no universal symbols 
%DEBUG-I-INITIAL, language is UNKNOWN, module set to SHARESARITH 
DBG> 
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This example shows the output of the ANALYZE/PROCESS command when 
used with the /FULL qualifier on an Alpha system. ¢ 


$ INSTALL 

INSTALL> ADD SYSSLIBRARY:DELTA 
INSTALL> EXIT 

$ DEFINE LIBSDEBUG DELTA 

$ ANALYZE/PROCESS/FULL PCFS_SERVER. DMP 


RO = 004558452E524556 R1 = 00000000004F1080 R2 = 000000000000048C 
R3 = 0000000000000000 R4 = 0000000000000000 R5 = 0000000000000001 
R6 = 0000000000F380C0 R7 = 00000000000000E9 R8 = 00000000002D3F70 
R9 = 0000000000342FB8 R10 = 00000000002CE330 R11 = 0000000000000047 
R12 = 00000000005107C0 R13 = 0000000000F38140 R14 = 0000000000D5D5C8 
R15 = 00000000000000F0 R16 = 000000000003793C R17 = 00000000004F108C 
R18 = 0000000000000000 R19 = 00000000004F1C00 R20 = 00000000004F1C00 
R21 = FFFFFFFF8052C4B6 R22 = 0000000000000001 R23 = FFFFFFFF80042E90 
R24 = 0000000000000001 R25 = 0000000000000000 R26 = 0000000000002000 
R27 = 00000000000184A0 R28 = 0000000000000001 AP = 0000000000F37E10 
FP = QQQ0000000DEQED8 SP = 0000000000F38110 PC = 0000000000002000 
FREE PQ VA 00F50000 FREE Pl VA 7FE6A000 

Active ASTs 00 Enabled ASTs OF 

Current Privileges FFFFFFFF FFF7FFFF 

Event Flags 80000000 50000000 

Buffered I/O count/limit 32758/32767 

Direct I/O count/limit 32767/32767 

File count/limit 32720/32767 

Process count/limit 0/0 

Timer queue count/limit 32763/32767 

AST count/limit 32754/32767 

Enqueue count/limit 32760/32767 

Buffered I/O total 17353137 Direct I/O total 333631 


Link Date 8-SEP-1992 16:42:37.94 


Kernel stack 00000020 pagelets at 7FF92000 moved to 00F50000 

Exec stack 00000020 pagelets at 7FF96000 moved to 00F54000 

Vector page 00000002 pagelet at 7FFF0000 moved to 00F58000 

PIO (RMS) area 00000007 pagelets at 7FFD0000 moved to 00F5A000 

Image activator context 00000001 pagelet at 7FFDOE00 moved to 00F5C000 
User writeable context 00000008 pagelets at 7FFC0000 moved to 00F5E000 


Condition signalled to take dump: 
SSYSTEM-F-ACCVIO, access violation, reason mask=00, virtual 
address=00002000, PC=00002000, PS=0000001B 


AlphaVMS DELTA Version 1.5 

Exception - Signal reason = 0000000C 

00002000! 

In this example, the SYS$LIBRARY:DELTA image is installed on an Alpha 
system by invoking the Install utility. Next, the logical LIBS|DEBUG 

is defined as DELTA in order to use the Delta Debugger (DELTA). The 
ANALYZE/PROCESS_DUMP command displays exception information and 


then a prompt. You can analyze the stack or other information provided to 
you in the dump.¢ 


DCLI-33 


ANALYZE/RMS_FILE 


ANALYZE/RMS_FILE 


Format 
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Invokes the Analyze/RMS_File utility, which is used to inspect and analyze 
the internal structure of an OpenVMS RMS file. The /RMS_FILE qualifier is 
required. For a complete description of the Analyze/RMS_File utility, see the 
OpenVMS Record Management Utilities Reference Manual. 


ANALYZE/RMS_FILE _ filespec{,...] 


ANALYZE/SYSTEM 


ANALYZE/SYSTEM 


Format 


Invokes the System Dump Analyzer utility, which analyzes a running system. 
The /SYSTEM qualifier is required. For a complete description of the System 
Dump Analyzer utility on Alpha, see the OpenVMS Alpha System Dump Analyzer 
Utility Manual. For a complete description of the System Dump Analyzer utility 
on VAX, see the OpenVMS VAX System Dump Analyzer Utility Manual. 


ANALYZE/SYSTEM 
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Adds the contents of one or more specified input files to the end of the specified 
output file. 


APPEND _input-filespec[,...] output-filespec 


input-filespec{....] 

Specifies the names of one or more input files to be appended. Multiple input files 
are appended to the output file in the order specified. If you specify more than 
one input file, separate each file specification with either a comma (,) or a plus 
sign (+). 


The asterisk (*) and the percent sign (%) wildcard characters are allowed in the 
input file specifications. 


output-filespec 
Specifies the name of the file to which the input files will be appended. 


You must specify at least one field in the output file specification. If you do not 
specify a device or directory, the APPEND command uses the current default 
device and directory. Other unspecified fields default to the corresponding fields 
of the first input file specification. 


If you use the asterisk (*) wildcard character in any fields of the output file 
specification, the APPEND command uses the corresponding field of the input 
file specification. If you are appending more than one input file, the APPEND 
command uses the corresponding fields from the first input file. 


The APPEND command is similar in syntax and function to the COPY command. 
Normally, the APPEND command adds the contents of one or more files to the 
end of an existing file without incrementing the version number. The /NEW_ 
VERSION qualifier causes the APPEND command to create a new output file if 
no file with that name exists. 


Note that there are special considerations for using the APPEND command with 
DECwindows compound documents. For more information, see the Guide to 
OpenVMS File Applications. 


/ALLOCATION=number-of-blocks 

Forces the initial allocation of the output file to the specified number of 512-byte 
blocks. If you do not specify the /ALLOCATION qualifier, or if you specify it 
without the number-of-blocks parameter, the initial allocation of the output file is 
determined by the size of the input file. 


The allocation size is applied only if a new file is actually created by using the 
/NEW_VERSION qualifier. 


APPEND 


/BACKUP 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /BACKUP qualifier selects files according to the dates of their most recent 
backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/BEFORE[=time] 

Selects only those files dated prior to the specified time. You can specify time 
as absolute time, as a combination of absolute and delta times, or as one of 

the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


/BY_OWNER[=uic] 
Selects only those files whose owner user identification code (UIC) matches the 
specified owner UIC. The default UIC is that of the current process. 


Specify the UIC by using standard UIC format as described in the OpenVMS 
User’s Manual. 


/CONFIRM 

/NOCONFIRM (default) 

Controls whether a request is issued before each append operation to confirm that 
the operation should be performed on that file. The following responses are valid: 


YES NO QUIT 
TRUE FALSE 
1 0 ALL 


You can use any combination of uppercase and lowercase letters for word 
responses. Word responses can be abbreviated to one or more letters (for example, 
T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative 
answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, 

and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that 
you want to stop processing the command at that point. When you respond by 
entering ALL, the command continues to process, but no further prompts are 
given. If you type a response other than one of those in the list, DCL issues an 
error message and redisplays the prompt. 


/CONTIGUOUS 

/INOCONTIGUOUS 

Specifies that the output file must occupy physically contiguous disk blocks. By 
default, the APPEND command creates an output file in the same format as the 
corresponding input file and does not report an error if not enough space exists for 
a contiguous allocation. This qualifier is relevant only with the /NEW_VERSION 
qualifier. 
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If an input file is contiguous, the APPEND command attempts to create a 
contiguous output file, but does not report an error if there is not enough space. 
If you append multiple input files of different formats, the output file may or may 
not be contiguous. Use the /CONTIGUOUS qualifier to ensure that the output 
file is contiguous. 


/CREATED (default) 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The 
/CREATED qualifier selects files based on their dates of creation. This qualifier is 
incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which 
also allow you to select files according to time attributes. If you specify none of 
these four time qualifiers, the default is the /CREATED qualifier. 


/EXCLUDE=(filespecf....]) 

Excludes the specified files from the append operation. You can include a 
directory but not a device in the file specification. Wildcard characters (* and 
%) are allowed in the file specification. However, you cannot use relative version 
numbers to exclude a specific version. If you specify only one file, you can omit 
the parentheses. 


/EXPIRED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /EXPIRED qualifier selects files according to their expiration dates.: (The 
expiration date is set with the SET FILE/EXPIRATION_DATE command.) 
The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/EXTENSION=number-of-blocks 

Specifies the number of blocks to be added to the output file each time the file 

is extended. When you specify the /EXTENSION qualifier, the /NEW_VERSION 
qualifier is assumed and need not be typed on the command line. This qualifier is 
relevant only with the /NEW_VERSION qualifier. 


The extension value is applied only if a new file is actually created. 


/LOG 

/NOLOG (default) 

Controls whether the APPEND command displays the file specifications of each 
file appended. If the /LOG qualifier is specified, the command displays the file 
specifications of the input and output files as well as the number of blocks or 
records appended after each append operation. 


/MODIFIED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /MODIFIED qualifier selects files according to the dates on which they were 
last modified. This qualifier is incompatible with the /BACKUP, /CREATED, 
and /EXPIRED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time modifiers, the default is the 
/CREATED qualifier. 


/NEW_VERSION 

/NONEW_VERSION (default) 

Controls whether the APPEND command creates a new output file if the specified 
output file does not exist. (By default, the specified output file already exists.) If 


Examples 


APPEND 


the specified output file does not already exist, use the /NEW_VERSION qualifier 
to create a new output file. If the output file does exist, the /NEW_VERSION 
qualifier is ignored and the input file is appended to the output file. 


/PROTECTION=(ownership[:access]|....]) 
Specifies protection for the output file. 


e Specify the ownership parameter as system (S), owner (O), group (G), or 
world (W ). 


e Specify the access parameter as read (R), write (W), execute (E), or delete 
(D). 


The default, protection, including any protection attributes not specified, is that 
of the existing output file. If no output file exists, the current default protection 
applies. This qualifier is relevant only with the /NEW_VERSION qualifier. 


For more information on specifying protection codes, see the OpenVMS Guide to 
System Security. 


/READ_CHECK 
/NOREAD_CHECK (default) 
Reads each record in the input files twice to verify that it has been read correctly. 


/SINCE[=time] . 

Selects only those files dated after the specified time. You can specify time 

as absolute time, as a combination of absolute and delta times, or as one of 
the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


/WRITE_CHECK 

/NOWRITE_CHECK (default) 

Reads each record in the output file after the record is written to verify that it 
was appended successfully and that the output file can subsequently be read 
without error. 


1. $ APPEND TEST3.DAT TESTALL.DAT 


The APPEND command appends the contents of the file TEST3.DAT from the 
default disk and directory to the file TESTALL.DAT, also located on the default 
disk and directory. 


2. § APPEND/NEW_VERSION/LOG *.TXT MEM.SUM 
tAPPEND-I-CREATED, USE$: [MAL]MEM.SUM;1 created — 
tAPPEND-S-COPIED, USES: [MALJA.TXT;2 copied to USE$:[MAL]MEM.SUM;1 (1 block) 
SAPPEND-S-APPENDED, USE$:[MAL]B.TXT;3 appended to USES$:{MAL]MEM.SUM;1 (3 records) 
tAPPEND-S-APPENDED, USE$:[MAL]G.TXT;7 appended to USE$:[MAL]MEM.SUM;1 (51 records) 


The APPEND command appends all files with file types of .TXT to a file named 
MEM.SUM. The /LOG qualifier requests a display of the specifications of each 
input file appended. If the file MEM.SUM does not exist, the APPEND command 
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creates it, as the output shows. The number of blocks or records shown in the | 
output refers to the source file and not to the target file total. 


3. $ APPEND/LOG A.DAT, B.MEM C.* 
SAPPEND-S-APPENDED, USE$:[MAL]A.DAT;4 appended to USE$:[MAL]C.DAT;4 (2 records) 
SAPPEND-S-APPENDED, USE$:[MAL]B.MEM;5 appended to USES$:[MAL]C.DAT;4 (29 records) 


The APPEND command appends the files A.DAT and B.MEM to the file C.DAT, 
which must already exist. 


4, $ APPEND/LOG A.*  B.* 
SAPPEND-S-APPENDED, USE$:[MAL]A.DAT;5 appended to USE$:[MAL]B.DAT;1 (5 records) 
SAPPEND-S-APPENDED, USE$:[MAL]A.DOC;2 appended to USE$:[MAL]B.DAT;1 (1 record) 


Both the input and output file specifications contain wildcard characters in the 

file type field. The APPEND command appends each file with a file name of A to 
an existing file with B as its file name. The file type of the first mp file located 
determines the output file type. 


5. § APPEND BOSTON"JOHN SMITH YANKEE": :DEMO01.DAT, DEMO2.DAT 
$ To: DALLAS::DISK1:[MODEL.TEST]TEST.DAT 


This APPEND command adds the contents of the files DEMO1.DAT and 
DEMO2.DAT at remote node BOSTON to the end of the file TEST.DAT at 
remote node DALLAS. 
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Creates a logical name and assigns an equivalence string, or a list of strings, 
to the specified logical name. If you specify an existing logical name, the new 
equivalence name replaces the existing equivalence name. 


ASSIGN equivalence-namef{,...] logical-name[:] 


equivalence-namef{,...] 

Specifies a character string of 1 to 255 characters. Defines the equivalence name, 
usually a file specification, device name, or other logical name, to be associated - 
with the logical name in the specified logical name table. If the string contains 
other than uppercase alphanumeric, dollar sign ($), or underscore (_) characters, 
enclose it in quotation marks (“”). Use two sets of quotation marks (““””) to 
denote an actual quotation mark within the string. Specifying more than one 
equivalence name for a logical name creates a search list. 


When you specify an equivalence name that will be used as a file specification, 
you must include the punctuation marks (colons (:), brackets ([]), and periods 
(.)) that would be required if the equivalence name were used directly as a file 
specification. Therefore, if you specify a device name as an equivalence name, 
terminate the device name with a colon. 


The ASSIGN command allows you to assign the same logical name to more than 
one equivalence name. When you specify more than one equivalence name for a 
logical name, you create a search list. For more information on search lists, see 

the OpenVMS User’s Manual. 


logical-name[:] 

Specifies the logical name string, which is a character string containing up to 255 
characters. You choose a logical name to represent the eamvaloare name in the 
specified logical name table. 


If the string contains other than uppercase alphanumeric, dollar sign, or 
underscore characters, enclose it in quotation marks. Use two sets of quotation 
marks to denote an actual quotation mark. If you terminate the logical- 

name parameter with a colon, the system removes the colon before placing 

the name in a logical name table. (This differs from the DEFINE command, 
which saves the colon.) If the logical name is to be entered into the process 
directory (LNM$PROCESS_DIRECTORY) or system directory (LNM$SYSTEM_ 
DIRECTORY) logical name tables, then the name may only have from 1 to 31 
alphanumeric characters (including the dollar sign and underscore). By default, 
the logical name is placed in the process logical name table. 


If the logical name contains any characters other than alphanumeric characters, 
the dollar sign, or the underscore, enclose the name in quotation marks. If the 
logical name contains quotation marks, enclose the name in quotation marks and 
use two sets of quotation marks in the places where you want one set of quotation 
marks to occur. Note that if you enclose a name in quotation marks, the case of 
alphabetic characters is preserved. 
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The ASSIGN command creates an entry in a logical name table by defining a 
logical name to stand for one or more equivalence names. An equivalence name 
can be a device name, another logical name, a file specification, or any other 
string. 


To specify the logical name table where you want to enter a logical name, use the 
/PROCESS, /JOB, /GROUP, /SYSTEM, or /TABLE qualifier. If you enter more 
than one of these qualifiers, only the last one entered is accepted. If you do not 
specify a table, the default is /TABLE=LNM$PROCESS (or /PROCESS). 


To specify the access mode of the logical name you are creating, use the /USER_ 
MODE, the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. If you 
enter more than one of these qualifiers, only the last one entered is accepted. If 
you do not specify an access mode, then a supervisor-mode name is created. You 
can create a logical name in the same mode as the table in which you are placing 
the name or in an outer mode. (User mode is the outermost mode; executive 
mode is the innermost mode.) 


You can enter more than one logical name with the same name in the same logical 
name table, as long as each name has a different access mode. (However, if an 
existing logical name within a table has the NO_ALIAS attribute, you cannot use 
the same name to create a logical name in an outer mode in this table.) 


If you create a logical name with the same name, in the same table, and in the 
same mode as an existing name, the new logical name assignment replaces the 
existing assignment. 


You can also use the DEFINE command to create logical names. To delete a 
logical name from a table, use the DEASSIGN command. 


Note 


Avoid assigning a logical name that matches the file name of an 
executable image in SYS$SYSTEM:. Such an assignment will prohibit 
you from invoking that image. 


For additional information on how to create and use logical names, see the 
OpenVMS User’s Manual. 


/EXECUTIVE_MODE 
Requires SYSNAM (system logical name) privilege. 


Creates an executive-mode logical name. If you specify executive mode, but do 
not have SYSNAM privilege, a supervisor-mode logical name is created. The 
mode of the logical name must be the same as or external to (less privileged than) 
the mode of the table in which you are placing the name. 


/GROUP 
Requires SYSPRV (system privilege) or GRPNAM (group logical name) 
privilege. 


ASSIGN 


Places the logical name in the group logical name table. Other users who 
have the same group number in their user identification codes (UICs) can 
access the logical name. The /GROUP qualifier is synonymous with the 
/TABLE=LNM$GROUP qualifier. 


/JOB 

Places the logical name in the jobwide logical name table. All processes within 

the same job tree as the process creating the logical name can access the logical 
name. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier. 


/LOG (default) 
/NOLOG 


Displays a message when a new logical name supersedes an existing name. 


/NAME_ATTRIBUTES[=(keyword{,...])] 
Specifies the attributes for a logical name. By default, no attributes are set. You 
can specify the following keywords for attributes: 


CONFINE Does not copy the logical name into a spawned subprocess; this 
keyword is relevant only for logical names in a private table. 


NO_ALIAS Prohibits creation of logical names with the same name in an 
outer (less privileged) access mode within the specified table. If 
another logical name with the same name and an outer access 
mode already exists in this table, the name is deleted. 


If you specify only one keyword, you can omit the parentheses. Only the 
attributes you specify are set. 


/PROCESS (default) 
Places the logical name in the process logical name table. The /PROCESS 
qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier. 


/SUPERVISOR_MODE (default) . 
Creates a supervisor-mode logical name in the specified table. 


ISYSTEM 
Requires SYSNAM (system logical name) or SYSPRV (system privilege) 
privilege. 


Places the logical name in the system logical name table. All system users 
can access the logical name. The /SYSTEM qualifier is synonymous with the 
/TABLE=LNM$SYSTEM qualifier. 


/TABLE=name 
Requires write (W) access to the table if the table is shareable. 


Specifies the logical name table in which the logical name is to be entered. You 
can use the /TABLE qualifier to specify a user-defined logical name table (created 
with the CREATE/NAME_TABLE command); to specify the process, job, group, 
or system logical name tables; or to specify the process or system logical name 
directory tables. 


If you specify the table name using a logical name that has more than one 
translation, the logical name is placed in the first table found. For example, if 
you specify ASSIGN/TABLE=LNM$FILE_DEV and LNM$FILE_DEV is equated 
to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the 
logical name is placed in LNM$PROCESS. 
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If you do not explicitly specify the /TABLE qualifier, the default is the 
/TABLE=LNM$PROCESS qualifier. 


/TRANSLATION_ATTRIBUTES[=(keyword,...])] 
Equivalence-name qualifier. 


Specifies attributes of the equivalence-name parameter. Possible keywords are as 
follows: 


CONCEALED Indicates that the equivalence string is the name of a concealed 
device. 
When a concealed device name is defined, the system displays 
the logical name, rather than the equivalence string, in 
messages that refer to the device. If you specified the 
CONCEALED attribute, then the equivalence string must 
be a physical device name. 


TERMINAL Indicates that the equivalence string should not be translated 
iteratively; logical name translation should terminate with the 
current equivalence string. 


If you specify only one keyword, you can omit the parentheses. Only the 
attributes you specify are set. 


Note that different equivalence strings of the same logical name can have 
different translation attributes specified. 


/USER_MODE 
Creates a user-mode logical name in the specified table. 


If you specify a user-mode logical name in the process logical name table, that 
logical name is used for the execution of a single image only; user-mode entries 
are deleted from the logical name table when any image executing in the process 
exits; that is, after any DCL command that executes an image or user program 
completes execution. Also, user-mode logical names are automatically deleted 
when invoking and exiting a command procedure. 


_1. $ ASSIGN S$DISK1:[ACCOUNTS.MEMOS] MEMOSD 


The ASSIGN command in this example equates the partial file specification 
$DISK1:[ACCOUNTS.MEMOS] to the logical name MEMOSD. 


2. $ ASSIGN/USER_MODE $DISK1:[ACCOUNTS.MEMOS]WATER.TXT TM1 


The ASSIGN command in this example equates the logical name TM1 to a 
file specification. After the next image runs, the logical name is deassigned 
automatically. 


8. $ ASSIGN XXX1:[CHARLES] CHARLIE 
$ PRINT CHARLIE:TEST.DAT 
Job 274 entered on queue SYSSPRINT 


The ASSIGN command in this example associates the logical name CHARLIE 
with the directory name [CHARLES] on the disk XXX1. Subsequent 
references to the logical name CHARLIE result in the correspondence 
between the logical name CHARLIE and the disk and directory specified. The 
PRINT command queues a copy of the file XXX1:[;CHARLES]TEST.DAT to the 
system printer. 


4. 


ASSIGN 


$ ASSIGN YYY2: TEMP: 
$ SHOW LOGICAL TEMP 

"TEMP" = "YYY2:" (LNMSPROCESS TABLE) 
$ DEASSIGN TEMP ~ 


The ASSIGN command in this example equates the logical name TEMP 

to the device YYY2. TEMP is created in supervisor mode and placed in 

the process logical name table. The SHOW LOGICAL command verifies 
that the logical name assignment was made. Note that the logical name 
TEMP was terminated with a colon in the ASSIGN command, but that the 
command interpreter deleted the colon before placing the name in the logical 
name table. Thus, you can specify TEMP without a colon in the subsequent 
DEASSIGN command. You should omit the colon in the SHOW LOGICAL 
command (for example, SHOW LOGICAL TEMP). 


$ MOUNT TTT1: MASTER TAPE 
$ ASSIGN TAPE:NAMES.DAT PAYROLL 
$ RUN PAYROLL 


The MOUNT command in this example establishes the logical name TAPE 
for the device TTT1, which has the volume labeled MASTER mounted on 

it. The ASSIGN command equates the logical name PAYROLL with the file 
named NAMES.DAT on the logical device TAPE. Thus, an OPEN request in a 
program referring to the logical name PAYROLL results in the correspondence 
between the logical name PAYROLL and the file NAMES.DAT on the tape 
whose volume label is MASTER. 


$ CREATE/NAME TABLE TABLE] 

$ ASSIGN/TABLE=LNMSPROCESS DIRECTORY TABLE1,- 

$ LNMSPROCESS, LNM$JOB, LNMSGROUP, LNMSSYSTEM LNMS$FILE DEV 
$ ASSIGN/TABLE=TABLE1 - = 
_$ /TRANSLATION ATTRIBUTES=CONCEALED DBAl: WORK _DISK 


The CREATE/NAME_TABLE command in this example creates the process 
private logical name table TABLE1. 


The first ASSIGN command ensures that TABLE1 is searched first in any 
logical name translation of a file specification or device name (because 
TABLE is the first item in the equivalence string for the logical name 
LNM$FILE_DEV, which determines the default search sequence of logical 
name tables whenever a device or file specification is translated). 


The second ASSIGN command assigns the logical name WORK_DISK to the 
physical device DBA1, and places the name in TABLE1. The logical name 
has the concealed attribute. Therefore, the logical name WORK_DISK will be 
displayed in system messages. 


$ ASSIGN/TABLE=LNM$PROCESS/TABLE=LNM$GROUP DBAO: SYSFILES 
$ SHOW LOGICAL SYSFILES 
"SYSFILES" = "DBAQ:" (LNMSGROUP_ 000240) 


The ASSIGN command in this example contains conflicting qualifiers. When 
you specify conflicting qualifiers, the ASSIGN command uses the last qualifier 
specified. The response from the SHOW LOGICAL command indicates that 
the name was placed in the group logical name table. 
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$ ASSIGN/TABLE=LNMSGROUP 'FSTRNLNM("SYSSCOMMAND")’ TERMINAL 
%DCL-I-SUPERSEDE, previous value of TERMINAL has been superseded 


The ASSIGN command in this example uses the lexical function FSTRNLNM 
to translate the logical name SYS$COMMAND and use the result as the 
equivalence name for the logical name TERMINAL. The message from the 
ASSIGN command indicates that an entry for the logical name TERMINAL 
already existed in the group logical name table, and that the new entry has 
replaced the previous one. 


If this command is used in a LOGIN.COM file, the entry for TERMINAL will 
be redefined at the beginning of each terminal session. The current process 
and any subprocesses it creates can execute images that use the logical name 
TERMINAL to write messages to the current terminal device. 


$ ASSIGN DALLAS::DMA1: DATA 


The ASSIGN command in this example associates the logical name DATA 
with the device specification DMA1 on remote node DALLAS. Subsequent 
references to the logical name DATA result in references to the disk on the 
remote node. 


$ CREATE AVERAGE.COM 

$ ASSIGN/USER_MODE SYS$COMMAND: SYS$INPUT 
$ EDIT/EDT AVERAGE.FOR 

$ FORTRAN AVERAGE 

$ LINK AVERAGE 

$ RUN AVERAGE 


$ @AVERAGE.COM 


The CREATE command in this example creates the command procedure 
AVERAGE.COM. Then the command procedure is executed. 


The command procedure uses the ASSIGN command with the /USER_MODE 
qualifier to change temporarily the value of SYS$INPUT. When the EDT 
editor is invoked, it accepts input from the terminal. This allows you to 
create or modify the program AVERAGE.FOR interactively. 


When you exit from EDT, SYS$INPUT is reassigned to its original value 
(the input stream provided by the command procedure). Thus, when the 
program AVERAGE.FOR is ready to accept input, it looks for that input in 
the command procedure. 


ASSIGN/MERGE 
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Removes all jobs from one queue and merges them into another existing queue. 
This command does not affect jobs that are executing. 


Requires manage (M) access to both queues. 


ASSIGN/MERGE _target-queue[:] source-queue[:] 


target-queue[:] 
Specifies the name of the queue into which the jobs are being merged. 


source-queue[:] 
Specifies the name of the queue from which the jobs are being removed. 


The ASSIGN/MERGE command removes the pending jobs in one queue and 
places them in another queue. This command does not affect any executing 
jobs in either the target queue or the source queue. Jobs currently running in 
the source queue complete in that queue. This command is generally used with 
printer queues, although it can be used with batch queues. 


The ASSIGN/MERGE command is particularly useful when a line printer 
malfunctions. By entering the ASSIGN/MERGE command, you can reroute 
existing jobs to a different printing device. To perform the merge operation 
without losing or disrupting any jobs, stop the source queue with the STOP 
/QUEUE/NEXT command. Then enter the STOP/QUEUE/REQUEUE command 
to ensure that the current job on the source queue is requeued for processing on 
the target queue. (If the STOP/QUEUE/REQUEUE command fails to requeue 
the job, use the STOP/QUEUE/RESET command to regain control of the queue.) 
Once you enter the STOP commands, enter the ASSIGN/MERGE command. 


$ STOP/QUEUE/NEXT LPBO 
§ STOP/QUEUE/REQUEUE=LPA0 LPBO 
$ ASSIGN/MERGE LPAO LPBO 


In this example, the STOP/QUEUE/NEXT command prevents another job from 
executing on queue LPBO. The STOP/QUEUE/REQUEUE command requeues the 
current job running on LPBO to the target queue LPAO. The ASSIGN/MERGE 


command removes the remaining jobs from the LPBO printer queue and places 
them in the LPAO printer queue. 
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Assigns, or redirects, a logical queue to a single execution queue. The ASSIGN 
/QUEUE command can be used only with printer or terminal queues. 


Requires manage (M) access to both queues. 
ASSIGN/QUEUE queue-namef:] logical-queue-name[:] 


queue-name[:] | 
Specifies the name of the execution queue. The queue cannot be a logical queue, 
a generic queue, or a batch queue. 


logical-queue-name[:] 
Specifies the name of the logical queue. 


The ASSIGN/QUEUE command sets up a one-to-one correspondence between a 
logical queue and an execution queue. Jobs submitted to the logical queue are 
always queued to the specified execution queue for eventual printing. 


When you enter the ASSIGN/QUEUE command, the logical queue cannot be 
running. 


Once you initialize a logical queue, use the ASSIGN/QUEUVE command to 
associate the logical queue with an existing execution queue. You must perform 
the following tasks to set up a logical queue: 


1. Initialize the logical queue with the INITIALIZE/QUEUVE command. (Do not 
use the /START qualifier.) 


2. Assign the logical queue name to an existing execution queue. 
3. Start the logical queue with the START/QUEUE command. 


After you enter the START/QUEUE command for the logical queue, jobs can be 
sent to the logical queue for processing. 


1. $ INITIALIZE/QUEUE/DEFAULT=FLAG=ONE/START LPAO 
$ INITIALIZE/QUEUE TEST QUEUE 
$ ASSIGN/QUEUE LPAO TEST QUEUE 
$ START/QUEUE TEST QUEUE 


This example first initializes and starts the printer queue LPAO. The 
LPAO queue is set to have a flag page precede each job. The second 
INITIALIZE/QUEUE command creates the logical queue TEST_QUEUE. 
The ASSIGN/QUEUE command assigns the logical queue TEST_QUEUE to 
the printer queue LPAO. The START/QUEUE command starts the logical 
queue. 


ASSIGN/QUEUE 


2. $ INITIALIZE/QUEUE/START LPBO 


The ASSIGN/QUEUE command is not needed in this example because a 
logical queue is not being initialized. A printer queue is being initialized; 
LPBO is the name of a line printer. After you enter the INITIALIZE/QUEUE 
/START command, jobs can be queued to LPBO for printing. 
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ATTACH 


Format 


Parameter 


Description 


Qualifier 


DCLI--50 


Transfers control from your current process (which then hibernates) to the 
specified process. 


The ATTACH and SPAWN commands cannot be used if your terminal has 
an associated mailbox. 


ATTACH [process-name] 


process-name 

Specifies the name of a parent process or spawned subprocess to which control 
passes. The process must already exist, be part of your current job, and share the 
same input stream as your current process. However, the process cannot be your 
current process or a subprocess created with the /NOWAIT qualifier. 


Process names can contain from 1 to 15 alphanumeric characters. If a connection 
to the specified process cannot be made, an error message is displayed. . 


The process-name parameter is incompatible with the (IDENTIFICATION 
qualifier. 7 


The ATTACH command allows you to connect your input stream to another 
process. You can use the ATTACH command to change control from one 
subprocess to another subprocess or to the parent process. 


When you enter the ATTACH command, the parent or “source” process is put 
into hibernation, and your input stream is connected to the specified destination 
process. You can use the ATTACH command to connect to a subprocess that is 
part of a current job left hibernating as a result of the SPAWN/WAIT command or 
another ATTACH command as long as the connection is valid. (No connection can 
be made to the current process, to a process that is not part of the current job, 

or to a process that does not exist. If any of these connections are attempted, an 
error message is displayed.) 


You can also use the ATTACH command in conjunction with the SPAWN 
/WAIT command to return to a parent process without terminating the created 
subprocess. See the description of the SPAWN command for more details. 


ADENTIFICATION=pid 

Specifies the process identification (PID) of the process to which terminal control 
will be transferred. Leading zeros can be omitted. The /IDENTIFICATION 
qualifier is incompatible with the process-name parameter. 


If you omit the (IDENTIFICATION qualifier, you must specify a process name. 


ATTACH 


Examples 


1. § ATTACH JONES 2 


The ATTACH command transfers the terminal’s control to the subprocess 
JONES_2. 


2. $ ATTACH/IDENTIFICATION=30019 


The ATTACH command switches control from the current process to a process 
having the PID 30019. Notice that because the (IDENTIFICATION qualifier 


is specified, the process-name parameter is omitted. 
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BACKUP 


Format 
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Invokes the Backup utility (BACKUP) to perform one of the following backup 
operations: 


Make copies of disk files. 


Save disk files as data in a file created by BACKUP on disk or magnetic tape. 
(Files created by BACKUP are called save sets.) 


Restore disk files from a BACKUP save set. 
Compare disk files or files in a BACKUP save set with other disk files. 


List information about files in a BACKUP save set to an output device or file. 


You cannot invoke BACKUP to back up a system disk; a system disk must be 
bootstrapped to run. For a complete description of BACKUP and information on 
backing up the system disk, see the OpenVMS System Manager’s Manual and the 
OpenVMS System Management Utilities Reference Manual. 


BACKUP input-specifier output-specifier 


CALL 


Format 


Parameters 


CALL 


Transfers control to a labeled subroutine within a command procedure. 


CALL label [parameter [...]] 


label 

Specifies a label of 1 to 255 alphanumeric characters that appears as the first 
item on a command line. A label cannot contain embedded blanks. When 
the CALL command is executed, control passes to the command following the 
specified label. 


The label can precede or follow the CALL statement in the current command 
procedure. A label in a command procedure must be terminated with a colon (:). 
Labels for subroutines must be unique. 


Labels declared in inner procedure levels are inaccessible from outer levels, as in 
the following example: 


SCALL B 
$SUBROUTINE A 

$ B: SUBROUTINE 
$ ENDSUBROUTINE 
SENDSUBROUTINE 


In this example, the label B in subroutine A is inaccessible from the outer 


procedure level. 


parameter [...] 

Specifies from one to eight optional parameters to pass to the command 
procedure. Use quotation marks ("") to specify a null parameter. The parameters 
assign character string values to the symbols named P1, P2, and so on in the 
order of entry, to a maximum of eight. The symbols are local to the specified 
command procedure. Separate each parameter with one or more spaces. 


You can specify a parameter with a character string value containing 
alphanumeric or special characters, with the following restrictions: 


e The command interpreter converts alphabetic characters to uppercase and 
uses blanks to delimit each parameter. To pass a parameter that contains 
embedded blanks or lowercase letters, enclose the parameter in quotation 
marks (“”). 


e Ifthe first parameter begins with a slash (/), you must enclose the parameter 
in quotation marks. 


¢ To pass a parameter that contains quotation marks and spaces, enclose the 
entire string in quotation marks and use two sets of quotation marks within 
the string. For example: 


$ CALL SUB] "Never say ""quit""" 


When control transfers to SUB1, the parameter P1 is equated to the following 
string: 


Never say "quit" 
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If a string contains quotation marks and does not contain spaces, the 
quotation marks are preserved in the string and the letters within the 
quotation marks remain in lowercase. For example: 


$ CALL SUB2 abe"def"ghi 
When control transfers to SUB2, the parameter P1 is equated to the string: 
ABCdefGHI 


To use a symbol as a parameter, enclose the symbol in single quotation marks 
(‘’) to force symbol substitution. For example: 


$ NAME = "JOHNSON" 


$ CALL INFO ‘NAME’ 


The single quotation marks cause the value “JOHNSON?” to be substituted for 
the symbol ‘NAME’. Therefore, the parameter “JOHNSON?” is passed as P1 to the 
subroutine INFO. 


The CALL command transfers control to a labeled subroutine within a command 
procedure. The CALL command is similar to the @ (execute procedure) command 
in that it creates a new procedure level. The advantage of the CALL command 
is that it does not require files to be opened and closed to process the procedure. 
Using the CALL command also makes managing a set of procedures easier 
because they can all exist in one file rather than in several files. 


When you use the CALL command to transfer control to a subroutine, a new 
procedure level is created and the symbols P1 to P8 are assigned the values of 
the supplied arguments. Execution then proceeds until an EXIT command is 
encountered. At this point, control is transferred to the command line following 
the CALL command. 


Procedures can be nested to a maximum of 32 levels, which includes any 
combination of command procedure and subroutine calls. Local symbols and 
labels defined within a nested subroutine structure are treated the same way as 
if the routines had been invoked with the @ command; that is, labels are valid 
only for the subroutine level in which they are defined. 


Local symbols defined in an outer subroutine level are available to any subroutine 
levels at an inner nesting level; that is, the local symbols can be read, but 

they cannot be written to. If you assign a value to a symbol! that is local to an 
outer subroutine level, a new symbol is created at the current subroutine level. 
However, the symbol in the outer procedure level is not modified. 


The SUBROUTINE and ENDSUBROUTINE commands define the beginning and 
end of a subroutine. The label defining the entry point to the subroutine must 
appear either immediately before the SUBROUTINE command or on the same 
command line. 


A subroutine can have only one entry point. The subroutine must begin with the 
SUBROUTINE command as the first executable statement. If an EXIT command 
is not specified in the procedure, the ENDSUBROUTINE command functions as 
an EXIT command. 


Qualifier 


CALL 


The SUBROUTINE command performs two different functions depending 

on the context in which it is executed. If executed as the result of a CALL 
command, it initiates a new procedure level, defines the parameters P1 to P8 as 
specified in the CALL statement, and begins execution of the subroutine. If the 
SUBROUTINE verb is encountered in the execution flow of the procedure 
without having been invoked by a CALL command, all the commands 
following the SUBROUTINE command are skipped until the corresponding 
ENDSUBROUTINE command is encountered. 


Note 


The SUBROUTINE and ENDSUBROUTINE commands cannot be 
abbreviated to fewer than 4 characters. 


/OUTPUT=filespec 

Writes all output to the file or device specified. By default, the output is written 
to the current SYS$OUTPUT device and the output file type is LIS. System 
responses and error messages are written to SYS$COMMAND as well as to the 
specified file. If you specify /OUTPUT, the qualifier must immediately follow the 
CALL command. The asterisk (*) and the percent sign (%) wildcard characters 
are not allowed in the output file specification. 


You can also redefine SYS$OUTPUT to redirect the output from a command . 
procedure. If you place the following command as the first line in a command 
procedure, output will be directed to the file you specify: 


$ DEFINE SYSSOUTPUT filespec 


When the procedure exits, SYS$OUTPUT is restored to its original equivalence 
string. This produces the same result as using the /OUTPUT qualifier when you 
execute the command procedure. 
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$ 
$! CALL.COM 


$! Define subroutine SUB1 
$! 
$ SUB1: SUBROUTINE 


$ CALL SUB2 !Invoke SUB2 from within SUB1 
$ @FILE !Invoke another procedure command file 


$ EXIT 
$ ENDSUBROUTINE !End of SUB1 definition 
$! 
$! Define subroutine SUB2 
| 


$! 
$ SUB2: SUBROUTINE 


° 


$ EXIT 

$ ENDSUBROUTINE !End of SUB2 definition 

$! 

$! Start of main routine. At this point, both SUB1 and SUB2 
$! have been defined but none of the previous commands have 
$! been executed. 

$! 
$ START: 

$ CALL/OUTPUT=NAMES.LOG SUB1 "THIS IS P1" 


$ CALL SUB2 "THIS IS Pl" "THIS IS P2" 


$ EXIT !Exit this command procedure file 


The command procedure in this example shows how to use the CALL command 
to transfer control to labeled subroutines. The example also shows that you can 
call a subroutine or another command file from within a subroutine. The CALL 
command invokes the subroutine SUB1, directing output to the file NAMES.LOG 
and allowing other users write (W) access to the file. The subroutine SUB2 is 
called from within SUB1. The procedure executes SUB2 and then uses the @ 
(execute procedure) command to invoke the command procedure FILE.COM. 
When all the commands in SUB1 have executed, the CALL command in the main 
procedure calls SUB2 a second time. The procedure continues until SUB2 has 
executed. 


CANCEL 


Format 


Parameters 


Description 


CANCEL 


Cancels wakeup requests for a specified process, including wakeup requests 
scheduled with either the RUN command or the $SCHDWK system service. 


Requires one of the following: 
¢ Ownership of the process. 


¢ GROUP privilege to cancel scheduled wakeup requests for processes 
in the same group but not owned by you. 


¢ WORLD privilege to cancel scheduled wakeup requests for any 
process in the system. 


CANCEL §[[node-name::]process-name] 


node-name:: 

The name of the node on which the specified process is running. The node name 
can have as many as six alphanumeric characters. The two colons (::) count for 
two additional characters, for a total of eight. 


You cannot specify a node name on a different VMScluster system from the 
current process. 


process-name 
The name of the process for which wakeup requests are to be canceled. The 
process name can have up to 15 alphanumeric characters. 


The specified process must be in the same group as the current process. 


The CANCEL command cancels scheduled wakeup requests for the specified 
process. | 


The CANCEL command does not delete the specified process. If the process is 
executing an image when the CANCEL command is issued for it, the process 
hibernates instead of exiting after the image completes execution. 


To delete a hibernating process for which wakeup requests have been canceled, 
use the STOP command. You can determine whether a subprocess has been 
deleted by entering the SHOW PROCESS command with the /SUBPROCESSES 


qualifier. 


A local process name can look like a remote process name. Therefore, 

if you specify ATHENS::SMITH, the system checks for a process named 
ATHENS::SMITH on the local node before checking node ATHENS for a process 
named SMITH. 


You also can use the IDENTIFICATION=pid qualifier to specify a process name. 
If you use the IDENTIFICATION qualifier and the process-name parameter 
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together, the qualifier overrides the parameter. If you do not specify either 

the process-name parameter or the /IDENTIFICATION qualifier, the CANCEL 
command cancels scheduled wakeup requests for the current (that is, the issuing) 
process. 


ADENTIFICATION=pid 
Identifies the process by its process identification ee You can omit leading 
zeros when you specify the PID. 


1. 


$ CANCEL CALENDAR 


The CANCEL command in this example cancels a wakeup request for a 
process named CALENDAR (which continues to hibernate until it is deleted 
with the STOP command). 


$ RUN/SCHEDULE=14:00 STATUS 
sRUN-S-PROC_ID, identification of created process is 0013012A 


$ CANCEL/IDENTIFICATION=13012A 


The RUN command in this example creates a process to execute the image 
STATUS. The process hibernates and is scheduled to be awakened at 14:00. 
Before the process is awakened, the CANCEL command cancels the wakeup 
request. 


$ RUN/PROCESS NAME=LIBRA/INTERVAL=1 :00 LIBRA 
$RUN-S-PROC_ID, identification of created process is 00130027 


$ CANCEL LIBRA 
$ STOP LIBRA 


The RUN command in this example creates a subprocess named LIBRA to 
execute the image LIBRA.EXE at hourly intervals. 


Subsequently, the CANCEL command cancels the wakeup request. The 
process continues to exist, but in a state of hibernation, until the STOP 
command deletes it. 


CLOSE 


Format 


Parameter 


Description 


Qualifiers 


Examples 


CLOSE 


Closes a file opened with the OPEN command and deassigns the associated 
logical name. 


CLOSE logical-name[:] 


logical-name[:] 
Specifies the logical name assigned to the file when it was opened with the OPEN 
command. 


Files that are opened for reading or writing at the command level remain open 
until closed with the CLOSE command, or until the process terminates. Ifa 
command procedure that opens a file terminates without closing the open file, the 
file remains open; the command interpreter does not automatically close it. 


/ERROR=label 

Specifies a label in the command procedure to receive control if the close operation 
results in an error. Overrides any ON condition action specified. If an error 
occurs and the target label is successfully given control, the global symbol 
$STATUS retains the code for the error that caused the error path to be taken. 


/LOG (default) 

INOLOG 

Generates a warning message when you attempt to close a file that was not 
opened by DCL. If you specify the /ERROR qualifier, the /LOG qualifier has no | 
effect. If the file has not been opened by DCL, the error branch is taken and no 
message is displayed. 


1. $ OPEN/READ INPUT FILE TEST.DAT 
$ READ LOOP: 
$ READ/END OF FILE=NO MORE INPUT FILE DATA LINE 


$ GOTO READ_LOOP 
$ NO_MORE: 
$ CLOSE INPUT FILE 


The OPEN command in this example opens the file TEST.DAT and assigns it 
the logical name of INPUT_FILE. The /END_OF_FILE qualifier on the READ 
command requests that, when the end-of-file (HOF) is reached, the command 
interpreter should transfer control to the line at the label NO_MORE. The 
CLOSE command closes the input file. 
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2. 


$ @READFILE 


$ STOP 
$ SHOW LOGICAL/PROCESS 


"INFILE" = " DB1" 
"QUTFILE" = " DB1" 
$ CLOSE INFILE — 
$ CLOSE OUTFILE 


In this example, pressing Ctrl/Y interrupts the execution of the command 
procedure READFILE.COM. Then, the STOP command stops the procedure. 
The SHOW LOGICAL/PROCESS command displays the names that currently 
exist in the process logical name table. Among the names listed are the 
logical names INFILE and OUTFILE, assigned by OPEN commands in the 
procedure READFILE.COM. 


The CLOSE commands close these files and deassign the logical names. 


CONNECT 


CONNECT 


Connects your physical terminal to a virtual terminal that is connected to another 
process. 


You must connect to a virtual terminal that is connected to a process 
with your user identification code (UIC). No other physical terminals 
may be connected to the virtual terminal. 


Format 
CONNECT virtual-terminal-name 

Parameter 
virtual-terminal-name 
Specifies the name of the virtual terminal to which you are connecting. A virtual 
terminal name always begins with the letters VITA. To determine the name of 
the virtual terminal that is connected to a process, enter the SHOW USERS 
command. 

Description 


The CONNECT command connects you to a separate process, as opposed to the 
SPAWN and ATTACH commands, which create and attach subprocesses. 


The CONNECT command is useful when you are logged in to the system using 
telecommunications lines. If there is noise over the line and you lose the carrier 
signal, your process does not terminate. After you log in again, you can reconnect 
to the original process and log out of your second process. 


To use the CONNECT command, the virtual terminal feature must be enabled 
for your system with the System Manager utility (SYSMAN) on OpenVMS Alpha 
systems and the System Generation utility (SYSGEN) on OpenVMS VAX systems. 


If virtual terminals are allowed on your system, use the SET TERMINAL 
/DISCONNECT/PERMANENT command to enable the virtual terminal © 
characteristic for a particular physical terminal. When you enable this 
characteristic, a virtual terminal is created when a user logs in to the physical 
terminal. The physical terminal is connected to the virtual terminal, which is in 
turn connected to the process. 


For new virtual terminals, you must first set the TT2$V_DISCONNECT bit in 
the TTY_DEFCHAR2 system parameter and reboot the system. This is done by 
creating the virtual device VTAO: using the ttdriver. For example: 





$ RUN SYSMAN IO CONNECT/NOADAPTER - 
_$ /DRIVER=SYS$LOADABLE IMAGES:SYSS$TTDRIVER VTAO: 
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$ RUN SYSGEN CONNECT /NOADAPTER/DRIVER=TTDRIVER VTAO: 


When the connection between the physical terminal and the virtual terminal 
is broken, you are logged out of your current process (and any images that the 
process is executing stop running) unless you have specified the /NOLOGOUT 
qualifier. 


If you have specified the /NOLOGOUT qualifier, the process remains connected 
to the virtual terminal. If the process is executing an image, it continues until 
the process needs terminal input or attempts to write to the terminal. At that 
point, the process waits until the physical terminal is reconnected to the virtual 
terminal. 


You can connect to a virtual terminal even if you are not currently using a 
virtual terminal. However, to log out of your current process you must use the 
CONNECT command with the /LOGOUT qualifier. If you connect to a virtual 
terminal from another virtual terminal, you can save your current process by 
using the /NOLOGOUT qualifier. 


/CONTINUE 

/NOCONTINUE (default) 

Controls whether the CONTINUE command is executed in the current process 
just before connecting to another process. This qualifier allows an interrupted 
image to continue processing after you connect to another process. 


The /CONTINUE qualifier is incompatible with the (LOGOUT qualifier. 


/LOGOUT (default) 

/NOLOGOUT 

Logs out your current process when you connect to another process using a 
virtual terminal. 


When you enter the CONNECT command from a process that is not connected 
to a virtual terminal, you must specify the /LOGOUT qualifier. Otherwise, DCL 
displays an error message. 


The /LOGOUT qualifier is incompatible with the /CONTINUE qualifier. 


1. $ RUN AVERAGE 


$ CONNECT/CONTINUE VTA72 


In this example, you use the RUN command to execute the image 
AVERAGE.EXE. You enter this command from a terminal that is connected to 
a virtual terminal. Next, you press Ctrl/Y to interrupt the image. After you 
interrupt the image, enter the CONNECT command with the /CONTINUE 
qualifier. This operation issues the CONTINUE command, so the image 
continues to run and connects you to another virtual terminal. You can 
reconnect to the process later. 


2. 


CONNECT 


$ SHOW USERS/FULL 


VAX/VMS User Processes at 22-DEC-1994 14:11:56.91 
Total number of users = 51, 


number of processes = 158 


Username Node Process Name PID Terminal 

KIDDER BUKETT KIDDER 29A0015E FTA3: 

KIDDER BUKETT _FTA4: 29A0015F FTA4: 

KIDDER RACEY1 KIDDER 05800062 FTA5: 

KIDDER RACEY1 DECWSMWM 0580005D MBA44: Disconnected 

KIDDER RACEY1 DECWSSESSION 05800059 

KIDDER RACEY1 VUES$KIDDER_2 0580005E (subprocess of 05800059) 

KIDDER RACEY1 VUESKIDDER_3 0580005F MBA51: Disconnected 

KIDDER RACEY1 VUESKIDDER 4 05800060 MBA53: Disconnected 

SMITH BUKETT SMITH 29A002C1 FTA7: 

SMITH BUKETT SMITH 1 29A006C2 (subprocess of 29A002C1) 

SMITH BUKETT SMITH 2 29A00244 (subprocess of 29A002C1) 

SMITH HAMLET SMITH 24800126 FTA6; 

SMITH HAMLET DECWSBANNER 24800155 (subprocess of 24800126) 

SMITH HAMLET DECWSMWM 2480011F MBA170: Disconnected 
HAMLET DECWSSESSION 2480011D FTAS: 


SMITH 


$ CONNECT VTA273 


SMITH 
$ 


logged out at 22-DEC-1994 14:12:04.53 


This example shows how to reconnect to your original process after you have 
lost the carrier signal. First, you must log in again and create a new process. 
After you log in, enter the SHOW USERS/FULL command to determine the 
virtual terminal name for your initial process. Then enter the CONNECT 
command to connect to the virtual terminal associated with your original 
process. The process from which you enter the CONNECT command is logged 
out because you have not specified any qualifiers. 


When you reconnect to the original process, you continue running the image 
that you were running when you lost the carrier signal. In this example, the 
user SMITH was at interactive level when the connection was broken. 
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Resumes execution of a DCL command, a program, or a command procedure that 
was interrupted by pressing Ctrl/Y or Ctrl/C. You cannot resume execution of the 
image if you have entered a command that executes another image or if you have 
invoked a command procedure. 


CONTINUE 


None. 


The CONTINUE command enables you to resume processing an image or a 
command procedure that was interrupted by pressing Ctrl/Y or Ctrl/C. You 
cannot resume execution of the image if you have entered a command that 
executes another image or if you have invoked a command procedure. However, 
you can use CONTINUE after commands that do not execute separate images; for 
a list of these commands, see the OpenVMS User’s Manual. 


You can abbreviate the CONTINUE command to a single letter, C. 


The CONTINUE command serves as the target command of an IF or ON 
command in a command procedure. The CONTINUE command is also a target 
command when it follows a label that is the target of a GOTO command. In 
addition, you can use the CONTINUE command to resume processing of a 
program that has executed either a VAX FORTRAN PAUSE statement or a 
VAX COBOL-74 STOP literal statement. 


1. $ RUN MYPROGRAM A 
~ 
$ SHOW TIME 
14-DEC-1994 13:40:12 
$ CONTINUE 


In this example, the RUN command executes the program MYPROGRAM_A. 
While the program is running, pressing Ctrl/Y interrupts the image. The 
SHOW TIME command requests a display of the current date and time. The 
CONTINUE command resumes the image. 


2. § ON SEVERE ERROR THEN CONTINUE 


In this example, the command procedure statement requests the command 
interpreter to continue executing the procedure if any warning, error, or 
severe error status value is returned from the execution of a command or 
program. This ON statement overrides the default action, which is to exit 
from a procedure following errors or severe errors. 


CONVERT 


CONVERT 


Invokes the Convert utility, which copies records from one file to another and 
changes the organization and format of the input file to those of the output 
file. For a complete description of the Convert utility, see the OpenVMS Record 


Management Utilities Reference Manual. 


Format 
CONVERT _ input-filespec[,...] output-filespec 
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Converts a CDA supported revisable input file to another revisable or final form 
output file. 


Note 


You can use this command only if DECwindows Motif for OpenVMS is 
installed on your system. 


CONVERT/DOCUMENT _input-filespec output-filespec 


input-filespec 
Specifies the name of the input file to be converted. The default file type is .DDIF. 


output-filespec 
Specifies the name of the output file. The default file type is .DDIF. 


The CONVERT/DOCUMENT command lets you convert documents from one 
format to another. You specify the name and format of the input file (a file whose 
format is incompatible with the application that needs to read the file) and the 
output file (the file to be created in a new format). 


You can convert a file from one format to another if an input converter exists 
for the input file format and an output converter exists for the output file 
format. The default input and output file format is DDIF (DIGITAL Document 
Interchange Format). DDIF is a standard format for the storage and interchange 
of compound documents, which can include text, graphics, and images. 


DDIF input and output converters, in addition to several other converters, are 
installed with the CDA Base Services for DECwindows Motif for OpenVMS. Some 
of the converters support processing options, which ensure minimal changes when 
your input file is converted to a different output file format. Create an options 
file with the processing options you need before specifying the ey CONVERT 
/DOCUMENT command with the /OPTIONS qualifier. 


Every converter supports a message log option, which is a file name you specify 
and to which informational and error messages are logged during the conversion. 


/FORMAT=format-name : 
Specifies the encoding format of the input or output file. The default input and 
output format is DDIF. 


Input converters bundled with the CDA Base Services for DECwindows Motif 
for OpenVMS and the default file type for the file formats they support are as 
follows: 


CONVERT/DOCUMENT 


Input Format File Type 
DDIF .DDIF 
DTIF .DTIF 
TEXT TXT 


Output converters bundled with the CDA Base Services for DECwindows Motif 
for OpenVMS and the default file types for the file formats they support are as 
follows: 


Output Format File Type 

DDIF .DDIF 

DTIF .DTIF 

TEXT .TXT 

PS .PS 

ANALYSIS .CDA$ANALYSIS 


Digital’s CDA Converter Library is a layered product that offers several other 
document, graphics, image, and data table input and output converters. 
Independent software vendors also write CDA conforming applications and 
converters for the operating system. Contact your system manager for a complete 
list of converters available on your system. 


Analysis Output Converter 

The Analysis output converter produces an analysis of the intermediate 
representation of the input file. The analysis output file shows the named objects 
and values stored in the input file. Application programmers use an analysis 
output file for debugging purposes. 


Application end users use an analysis output file to determine whether an input 
file contains references or links to multiple subfiles. Each subfile must be copied 
separately across a network because subfiles are not automatically included when 
an input file is transferred across the network. ; 


You can search the analysis output file for all occurrences of the string “ERF_”. 
The following example shows that the image file “griffin.img” is linked to the 
DDIF compound document that is the input file: 


ERF LABEL ISO LATIN1 "griffin.img" ! Char. string. 
ERF LABEL TYPE RMS LABEL TYPE "$RMS: 
ERF CONTROL COPY REFERENCE ! Integer = 1 


Note that an analysis output file is intended as a programmer’s tool. The coded 
information in the file is not intended for modification but rather to examine the 
content of a file. The previous example shows how you can search analysis output 
for references to linked files. 


DDIF Input Converter 


The DDIF input converter converts a DDIF input file to an intermediate 
representation that is subsequently converted to the specified output file format. 
The following list summarizes the data mapping, conversion restrictions, external 
file references, and document syntax errors relevant to the DDIF input converter. 
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Data mapping 


The information in the DDIF input file maps directly to an intermediate 
representation. 


Conversion restrictions 


The DDIF input file does not lose any information when converted to the 
intermediate representation. 


However, if the DDIF input file is a newer version of the DDIF grammar than 
that understood by the DDIF input converter, data represented by the new 
grammar elements is lost. 


External file references . 


Any external file references within the DDIF input file are converted to the 
intermediate representation. 


The DDIF input converter makes no attempt to resolve external references, 
although the converter kernel can if requested by the output converter. 


Document syntax errors 


A document syntax error in the DDIF input file causes a fatal input 
processing error. If the DDIF input converter encounters a document syntax 
error, the conversion stops and no further input processing occurs. 


DDIF Output Converter 

The DDIF output converter creates a DDIF output file from the intermediate 
representation of the input file. The following list summarizes the data mapping 
and conversion restrictions relevant to the DDIF output converter. 


Data mapping 


The information in the intermediate representation of the input file maps 
directly to the DDIF output file. 


Conversion restrictions 


The intermediate representation of the input file does not lose any 
information when converted to the DDIF output file. 


DTIF Input Converter 


The DTIF input converter converts a DTIF input file to an intermediate 
representation that is subsequently converted to the specified output file format. 
The following list summarizes the data mapping, conversion restrictions, external 
file references, and document syntax errors relevant to the DTIF input converter. 


Data mapping 


The information in the DTIF input file maps directly to an intermediate 
representation. 


Conversion restrictions 


The DTIF input file does not lose any information when converted to the 
intermediate representation. 


However, if the DTIF input file is a newer version of the DTIF grammar than 
that understood by the DTIF front end, data represented by the new grammar 
elements is lost. 


External file references 


Any external file references within the DTIF input file are converted to the 
intermediate representation. 
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The DTIF input converter makes no attempt to resolve external references. : 


¢ Document syntax errors 


A document syntax error in the DTIF input file causes a fatal input processing 
error. If the DTIF input converter encounters a document syntax error, the 
conversion stops and no further input processing occurs. 


DTIF Output Converter 

The DTIF output converter converts the intermediate representation of the input 
file to a DTIF output file. The following list summarizes the data mapping, 
conversion restrictions, and external file references relevant to the DTIF output 
converter. 


e Data mapping 


The information in the intermediate representation of the input file maps 
directly to the DTIF output file. 


¢ Conversion restrictions 


The intermediate representation of the input file does not lose any 
information when converted to the DTIF output file. 


e External file references 


The DTIF output converter converts external file references stored in the 
intermediate representation of the input file but makes no attempt to resolve 
external references. 


Text Input Converter 

The Text input converter converts a Text (ISO Latin1) input file to an 
intermediate representation that is subsequently converted to the specified 
output file format. The following list summarizes the data mapping, conversion 
restrictions, external file references, and document syntax errors relevant to the 
Text input converter: 


e Data mapping 


The information in the text input file maps directly to an intermediate 
representation. Line breaks and form feeds are mapped to DDIF directives. 
One or more contiguous blank lines are interpreted as end-of-paragraph 
markers. 


If the text input file was entered as a DEC Multinational character set file 
on a character-cell terminal or terminal emulator, the following conversions 


occur: 
Original Character Converted Character 
Concurrency sign Diaeresis 

Capital OE ligature - Multiplication sign 

Capital Y with diaeresis Capital Y with acute accent 
Small oe ligature Division sign 

Small y with diaeresis Y with acute accent 


e Conversion restrictions 


The text input file does not lose any information when converted to the 
intermediate representation because no structure information is contained in 
a text file. 
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All nonprinting characters are converted to space characters. For example, 
characters introducing ANSI escape characters are converted to space 
characters. There is no attempt to interpret ANSI escape sequences. 


e External file references 
Text files do not contain external file references. 


¢ Document syntax errors 


Text files do not contain syntax, so syntax errors are not reported by the Text 
input converter. 


Text Output Converter 

The Text output converter converts the intermediate representation of the input 
file to a Text output file. The following list summarizes the data mapping and 
conversion restrictions relevant to the Text output converter. 


¢ Data mapping 


All Latin1 text in the intermediate representation of the input file is 
converted to the text output file. 


When converting an input file to a text output file, you should be aware 

that text output files can contain only textual content and minimal formatting 
such as line feeds, page breaks, and tabs. The Text output converter preserves 
formatting information to the extent possible. Page coordinates convert to the 
nearest character cell (line,column) position. 


e Conversion restrictions 


All graphics, images, and text attributes in the intermediate representation of 
the input file are lost when converted to the text output file. 


Because a monospace font is used, it is possible some text may be lost due 
to overwriting to preserve the layout. It is also possible that lines can be 
truncated if the specified page width is smaller than the page width specified 
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use the OVERRIDE_FORMAT processing option because, in that case, the 
document’s format information is ignored. 


PostScript Output Converter 

The PostScript output converter converts the intermediate representation of the 
input file to a PostScript output file. The following list summarizes the data 
mapping and conversion restrictions relevant to the PostScript output converter. 


e Data mapping 


The information in the intermediate representation of the input file maps 
directly to the PostScript output file. 


e Conversion restrictions 


The intermediate representation of the input file does not lose any 
information when converted to the PostScript output file. 


/MESSAGE_FILE=filespec 

/NOMESSAGE_FILE (default) 

Turns on message logging for document conversion. Messages output by the 
input and output converters are directed to the file specified with filespec. If 
filespec is not specified, messages are output to SYS$ERROR. The default is 
/NOMESSAGE_FILE. 
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/OPTIONS=options-filename 

Specifies a text file that contains processing options applied to the input file and 
the output file during the conversion. The default file type for an options file is 
.CDA$OPTIONS. 


Creating the Options File 

You can create an options file prior to specifying the CONVERT/DOCUMENT 
command with the /OPTIONS qualifier. An options file is a text file with a 
default file type of .CDA$OPTIONS on the operating system. 


The options file contains all the processing options for your input file format and 
your output file format. Processing options help ensure minimal changes when 
your input file is converted to a different output file format. 


An options file is not required. Default processing options are applied 
automatically when you convert a file. However, you may require an options 
file if you need to use other than the default settings. 


Use the following guidelines to create an options file: 


¢ Begin each line of the options file with the keyword for the input or output 
format, followed by one or more spaces or tabs, or by a slash (/). 


For some file formats, such as DDIF and DTIF, there is an input converter 

and an output converter. You can restrict a processing option to only the 

input format or the output format by following the format RINGS with 
_INPUT or OUTPUT. 


e Specify only one processing option on each line when there are several options 
for the same input or output format. 


¢ Use uppercase and lowercase alphabetic characters, digits (0-9), dollar signs 
($), and underscores (_) to specify the processing options. 


¢ Use one or more spaces or tabs to precede values specified for a processing 
option. 

The following example is a typical entry in an options file: 

PS PAPER HEIGHT 10 


In this example, the extension OUTPUT is not required for the format keyword, 
since PostScript is available only as an output format. The value specified for 
PAPER_HEIGHT is in inches by default. 


If the options file includes options that do not apply to the converters for a 
particular conversion, those options are ignored. 


If you specify an invalid option for an input or output format or an invalid value 
for an option, you receive an error message. The processing options described in 
the following sections document any restrictions. 

Processing Options for Analysis Output 

The Analysis output converter supports the following options: 

¢ COMMENT DEFAULT_VALUES 


Inserts a comment character (!) at the beginning of lines generated by default 
values. (The comment prefix is also included on associated aggregate brackets 
and array parentheses where they may apply.) 
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COMMENT INHERITED_VALUES 


Inserts a comment character (!) at the beginning of lines generated by 
inherited values. (The comment prefix is also included on associated 
aggregate brackets and array parentheses where they may apply.) 


TRANSLATE_BYTE_STRINGS 
Overrides the default. For data of type BYTE STRING, the analysis output 
no longer displays the hexadecimal translation if all the characters in the 


byte string are printable characters (hex values 20 through 7E). This feature 
may be overridden by supplying the TRANSLATE_BYTE_STRINGS option. 


IMAGE_DATA 


Overrides the default. For the special case of byte string data for item 
DDIF$_IDU_PLANE_DATA (a bitmapped image), the analysis output 
previously included both a hexadecimal and an ASCII translation display, 
neither of which were of particular value to most users. With the new version, 
both displays will be replaced with the following comment: 


! *** Bit-mapped data not displayed here *** 


To retain the hexadecimal display, supply the IMAGE_DATA option. Even 
with this option turned on, there will be no translation into ASCII. 


INHERITANCE 


Specifies that the analysis is shown with attribute inheritance enabled. 
Inherited attributes are marked as “(Inherited value.]” in the output. This 
option also causes external references to be imported into the main document. 


Processing Options for Text Output 
The Text output converter supports the following options: 


ASCII_FALLBACK [ON,OFF] 


Causes the Text output converter to output text in 7-bit ASCII. The fallback 
representation of the characters is described in the ASCII standard. If this 
option is not specified, the default is OFF; if this option is specified without a 
value, the default is ON. 


CONTENT_MESSAGES [ON,OFF] 


Causes the Text output converter to put a message in the output file each 
time a nontext element is encountered in the intermediate representation of 
the input file. If this option is not specified, the default is OFF; if this option 
is specified without a value, the default is ON. 


HEIGHT value 


Specifies the maximum number of lines per page in your text output file. If 
you specify zero, the number of lines per page will correspond to the height 
specified in your document. If you also specify OVERRIDE_FORMAT, or if 
the document has no inherent page size, the document is formatted to the 
height value specified by this option. The default height is 66 lines. 


OVERRIDE_FORMAT [ON, OFF] 


Causes the Text output converter to ignore the document formatting 
information included in your document, so that the text is formatted in 

a single large galley per page that corresponds to the size of the page as 
specified by the HEIGHT and WIDTH processing options. If this option is not 
specified, the default is OFF; if this option is specified without a value, the 
default is ON. 
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SOFT_DIRECTIVES [ON, OFF] 


Causes the Text output converter to obey the soft directives contained in the 
document when creating your text output file. If this option is not specified, 
the default is OFF; if this option is specified without a value, the default is 
ON. 


WIDTH value 


Specifies the maximum number of columns of characters per page in your 
text output file. If you specify zero, the number of columns per page will 
correspond to the width specified in your document. If you also specify 
OVERRIDE_FORMAT, or if the document has no inherent page size, the 
document is formatted to the value specified by this processing option. If any 
lines of text exceed this width value, the additional columns are truncated. 
The default width is 80 characters. 


PostScript Output Converter 
The PostScript output converter supports the following options: 


PAPER_SIZE size 


Specifies the size of the paper to be used when formatting the resulting 
PostScript output file. Valid values for the size argument are as follows: 


Keyword Size 

AO — 841 x 1189 millimeters (33.13 x 46.85 inches) 
Al 594 x 841 millimeters (23.40 x 33.13 inches) 
A2 420 x 594 millimeters (16.55 x 23.40 inches) 
A3 297 x 420 millimeters (11.70 x 16.55 inches) 
A4 210 x 297 millimeters (8.27 x 11.70 inches) 
A 8.5 x 11 inches 

B 11 x 17 inches 

C 17 x 22 inches 

D 22 x 34 inches 

E 34 x 44 inches 

LEDGER 11 x 17 inches 

LEGAL 8.5 x 14 inches 

LETTER 8.5 x 11 inches 

LP 13.7 x 11 inches 

VT 8 x 5 inches 


The A paper size (8.5 x 11 inches) is the default. 


PAPER_HEIGHT height 


Specifies a paper size other than one of the predefined values provided. The 
default paper height is 11 inches. 


PAPER_WIDTH width 


Specifies a paper size other than one of the predefined sizes provided. The 
default paper width is 8.5 inches. 


DCLI-73 


CONVERT/DOCUMENT 


DCLI-74 


PAPER_TOP_MARGIN top-margin 


Specifies the width of the margin provided at the top of the page. The default 
value is 0.25 inch. 


PAPER_BOTTOM_MARGIN bottom-margin 


Specifies the width of the margin provided at the bottom of the page. The 
default value is 0.25 inch. 


PAPER_LEFT_MARGIN left-margin 


Specifies the width of the margin provided on the left-hand side of the page. 
The default value is 0.25 inch. 


PAPER_RIGHT_MARGIN right-margin 


Specifies the width of the margin provided on the right-hand side of the page. 
The default value is 0.25 inch. 


PAPER_ORIENTATION orientation 


Specifies the paper orientation to be used in the output PostScript file. The 
valid values for the orientation argument are as follows: 


Keyword Meaning 


PORTRAIT The page is oriented so that the larger dimension 
is parallel to the vertical axis. 
LANDSCAPE The page is oriented so that the larger dimension 


is parallel to the horizontal axis. 


The default is PORTRAIT. 


EIGHT_BIT_OUTPUT [ON, OFF] 


Specifies whether the PostScript output converter should use 8-bit output. 
The default value is ON. 


LAYOUT [ON,OFF] 


Specifies whether the PostScript output converter processes the layout 
specified in the DDIF document. The default value is ON. 


OUTPUT_BUFFER_SIZE output-buffer-size 


Specifies the size of the output buffer. The value you specify must be within 
the range 64 to 256. The default value is 132. 


PAGE_WRAP [ON,OFF] 


Specifies whether the PostScript output converter performs page wrapping of 
any text that would exceed the bottom margin. The default value is ON. 


SOFT_DIRECTIVES [ON,OFF] 


Specifies whether the PostScript output converter processes soft directives 
in the DDIF file in order to format output. (Soft directives specify such 
formatting commands as new line, new page, and tab.) If the PostScript 
output converter processes soft directives, the output file will look more like 
you intended. The default value is ON. 
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¢ WORD_WRAP [ON,OFF] 


Specifies whether the PostScript output converter performs word wrapping of 
any text that would exceed the right margin. The default value is ON. If you 
specify OFF, the PostScript output converter allows text to exceed the right 
margin. 


Domain Converter 


You might create an options file containing processing options that apply to any 
CDA supported tabular file format for which there is an input converter. Data 
tables and spreadsheets are examples of tabular file formats. 


To convert tabular input files to document output files, use the DTIF_TO_DDIF 

format name, followed by the processing options described in this section. Specify 
the DTIF_TO_DDIF processing options in addition to the processing options for a 
particular tabular input file format and a particular document output file format. 


You might want to convert tabular input files to document output files so that 
you can include textual representations of tables in reports and other documents. 
You should be aware, however, that you lose cell borders, headers, grid lines, 

all formulas, and font types when converting a tabular input file to a document 
output file. 


The domain converter supports the following options: 


¢ COLUMN_TITLE 


Displays the column titles as contained in the column attributes centered at 
the top of the column. 


¢ CURRENT_DATE 


Displays the current date and time in the bottom left corner of the page. The 
value is formatted according to the document’s specification for a default date 
and time. 


¢ DOCUMENT_DATE 


Displays the document date and time as contained in the document header 
in the top left corner of the page. The value is formatted according to the 
document’s specification for a default date and time. 


¢ DOCUMENT_TITLE 


Displays the document title or titles as contained in the document header 
centered at the top of the page, one string per line. 


¢ PAGE NUMBER 
Displays the current page number in the top right corner of the page. 
¢ PAPER_SIZE size 


Specifies the size of the paper to be used when formatting the resulting 
PostScript output file. Valid values for the size argument are as follows: 


Keyword Size 

AO 841 x 1189 millimeters (33.13 x 46.85 inches) 
Al 594 x 841 millimeters (23.40 x 33.13 inches) 
A2 420 x 594 millimeters (16.55 x 23.40 inches) 
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Keyword Size 

A3 297 x 420 millimeters (11.70 x 16.55 inches) 
A4 210 x 297 millimeters (8.27 x 11.70 inches) 
A5 148 x 210 millimeters (5.83 x 8.27 inches) 
A 8.5 x 11 inches (216 x 279 millimeters) 

B 11 x 17 inches (279 x 432 millimeters) 

B4 250 x 353 millimeters (9.84 x 13.90 inches) 
B5 176 x 250 millimeters (6.93 x 9.84 inches) 
C 17 x 22 inches (432 x 559 millimeters). 

C4 229 x 324 millimeters (9.01 x 12.76 inches) 
C5 162 x 229 millimeters (6.38 x 9.02 inches) 
D- 22 x 34 inches (559 x 864 millimeters) 

DL 110 x 220 millimeters (4.33 x 8.66 inches) 
E 34 x 44 inches (864 x 1118 millimeters) 
10x13_ 13 x 254 millimeters (15600 x 10 inches) 
ENVELOPE 

9x12_ 12 x 229 millimeters (14400 x 9 inches) 
ENVELOPE 

BUSINESS_ 9.5 x 105 millimeters (11400 x 4.18 inches) 
ENVELOPE 

EXECUTIVE 10 x 191 millimeters (12000 x 7.5 inches) 
LEDGER 11 x 17 inches (279 x 432 millimeters) 
LEGAL 8.5 x 14 inches (216 x 356 millimeters) 
LETTER 8.5 x 11 inches (216 x 279 millimeters) 

LP 13.7 x 11 inches (348 x 279 millimeters) 
VT 8 x 5 inches (203 x 127 millimeters) 


The A paper size (8.5 x 11 inches) is the default. 
PAPER_HEIGHT height 


Specifies a paper size other than one of the predefined values provided. The 
default paper height is 11 inches. 


PAPER_WIDTH width 


Specifies a paper size other than one of the predefined sizes provided. The 
default paper width is 8.5 inches. 


PAPER_TOP_MARGIN top-margin 


Specifies the width of the margin provided at the top of the page. The default 
value is 0.25 inch. 


PAPER_BOTTOM_MARGIN bottom-margin 


Specifies the width of the margin provided at the bottom of the page. The 
default value is 0.25 inch. 


PAPER_LEFT_MARGIN left-margin 


Specifies the width of the margin provided on the left side of the page. The 
default value is 0.25 inch. 


Example 
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e PAPER_RIGHT_MARGIN right-margin 


Specifies the width of the margin provided on the right side of the page. The 
default value is 0.25 inch. 


e PAPER ORIENTATION orientation 


Specifies the paper orientation to be used in the output file. The valid values 
for the orientation argument are as follows: 


Keyword Meaning 

PORTRAIT The page is oriented so that the larger dimension 
is parallel to the vertical axis. 

LANDSCAPE The page is oriented so that the larger dimension 


is parallel to the horizontal axis. 


The default is PORTRAIT. 


$ CONVERT/DOCUMENT/OPTIONS=MY OPTIONS.CDAS$OPTIONS - 


_$MY_INPUT.DTIF/FORMAT=DTIF MY OUTPUT. DDIF/FORMAT=DDIF 


This command converts an input file named MY_INPUT.DTIF, which has the 
DTIF format, to an output file named MY_OUTPUT.DDIF, which has the DDIF 
format. The specified options file is named MY_OPTIONS.CDA$OPTIONS. 
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Invokes the Convert/Reclaim utility, which makes empty buckets in Prolog 
3 indexed files available so that new records can be written in them. The 
/RECLAIM qualifier is required. For a complete description of the Convert 
/Reclaim utility, see the OpenVMS Record Management Utilities Reference 


Manual. 


CONVERT/RECLAIM filespec 


COPY 


Format 


Parameters 


COPY 


Creates a new file from one or more existing files. The COPY command can do 
the following: | 


¢ Copy an input file to an output file. 
¢ Concatenate two or more input files into a single output file. 


¢ Copy a group of input files to a group of output files. 
COPY _input-filespec[,...] output-filespec 


input-filespec{,...] 

Specifies the name of an existing file to be copied. The asterisk (*) and the 
percent sign (% ) wildcard characters are allowed. If you do not specify the device 
or directory, the COPY command uses your current default device and directory. 
If you specify more than one file, separate the file specifications with either 
commas (,) or plus signs (+). 


output-filespec 
Specifies the name of the output file into which the input is copied. 


You must specify at least one field in the output file specification. If you do not 
specify the device or directory, the COPY command uses your current default 
device and directory. The COPY command replaces any other missing fields 
(file name, file type, version number) with the corresponding field of the input 
file specification. If you specify more than one input file, the COPY command 
generally uses the fields from the first input file to determine any missing fields 


in the output file. 


Description 


You can use the asterisk (*) wildcard character in place of any two of the 
following: the file name, the file type, or the version number. The COPY 
command uses the corresponding field in the related input file to name the 
output file. 


The COPY command creates a new file from one or more existing files. If you do 
not specify the device or directory, the COPY command uses your current default 
device and directory. The COPY command can do the following: 


e Copy an input file to an output file. 
¢ Concatenate two or more input files into a single output file. 
e Copy a group of input files to a group of output files. 


The COPY command, by default, creates a single output file. When you specify 
more than one input file, the first input file is copied to the output file, and each 
subsequent input file is appended to the end of the output file. If a field of the 
output file specification is missing or contains an asterisk (* ) wildcard character, 
the COPY command uses the corresponding field from the first, or only, input file 


to name the output file. 
( 
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If you specify multiple input files with maximum record lengths, the COPY 
command gives the output file the maximum record length of the first input file. 
If the COPY command encounters a record in a subsequent input file that is 
longer than the maximum record length of the output file, it issues a message 
noting the incompatible file attributes and begins copying the next file. 


To create multiple output files, specify multiple input files and use at least one of 
the following: 


e An asterisk (*) wildcard character in the output directory specification, file 
name, file type, or version number field 


e Only a node name, a device name, or a directory specification as the output 
file specification 


e The /NOCONCATENATE qualifier 


When the COPY command creates multiple output files, it uses the corresponding 
field from each input file in the output file name. You also can use the asterisk 
(*) wildcard character in the output file specification to have COPY create more 
than one output file. For example: 


$ COPY A.A;1, B.B;1 *.C 


This COPY command creates the files A.C;1 and B.C;1 in the current default 
directory. When you specify multiple input and output files you can use the /LOG 
qualifier to verify that the files were copied as you intended. 


Note that there are special considerations for using the COPY command with 
DECwindows compound documents. For more information, see the Guide to 
OpenVMS File Applications. 


Version Numbers 


If you do not specify version numbers for input and output files, the COPY 
command (by default) assigns a version number to the output files that is either 
of the following: 


¢ The version number of the input file 


e A version number one greater than the highest version number of an existing 
file with the same file name and file type 


When you specify the output file version number by an asterisk (*) wildcard 
character, the COPY command uses the version numbers of the associated input 
files as the version numbers of the output files. 


If you specify the output file version number by an explicit version number, 
the COPY command uses that number for the output file specification. If a 
higher version of the output file exists, the COPY command issues a warning 
message and copies the file. If an equal version of the output file exists, the 
COPY command issues a message and does not copy the input file. 


File Protection and Creation/Revision Dates 


The COPY command considers an output file to be new when you specify any 
portion of the output file name explicitly. The COPY command sets the creation 
date for a new file to the current time and date. 


If you specify the output file by one or more asterisk (*) and percent sign (% ) 
wildcard characters, the COPY command uses the creation date of the input file. 


Qualifiers 


COPY 


The COPY command always sets the revision date of the output file to the current 
time and date; it sets the backup date to zero. The file system assigns the output 
file a new expiration date. (The file system sets expiration dates if retention is 
enabled; otherwise, it sets expiration dates to zero.) 


The protection and access control list (ACL) of the output file is determined by 
the following parameters, in the following order: 


¢ Protection of previously existing versions of the output file 
¢ Default Protection and ACL of the output directory 
e Process default file protection 


(Note that the BACKUP command takes the creation and revision dates as well 
as the file protection from the input file.) 


Use the /PROTECTION qualifier to change the output file protection. 


Normally, the owner of the output file will be the same as the creator of the 
output file. However, if a user with extended privileges creates the output file, 
the owner will be the owner of the parent directory or of a previous version of the 
output file if one exists. 


Extended privileges include any of the following: 
e SYSPRV (system privilege) or BYPASS 
e System user identification code (UIC) 


© GRPPRV (group privilege) if the owner of the parent directory (or previous 


version of the output file) is in the same group as the creator of the new 
output file 


e An identifier (with the resource attribute) representing the owner of the 
parent directory (or the previous version of the output file) 


Copying Directory Files 

If you copy a file that is a directory, the COPY command creates a new empty 
directory of the named directory. The COPY command does noé copy any files 
from the named directory to the new directory. See the examples section for 
examples of copying directory files. 


/ALLOCATION=number-of-blocks 

Forces the initial allocation of the output file to the specified number of 512-byte 
blocks. If you do not specify the /ALLOCATION qualifier, or if you specify it 
without the number-of-blocks parameter, the initial allocation of the output file is 
determined by the size of the input file being copied. 


/BACKUP 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /BACKUP qualifier selects files according to the dates of their most recent 
backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and 
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/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/BEFORE[=time] 

Selects only those files dated prior to the specified time. You can specify time 
as absolute time, as a combination of absolute and delta times, or as one of 

the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


/BY_OWNER[=uic] 
Selects only those files whose owner user identification code (UIC) matches the 
specified owner UIC. The default UIC is that of the current process. 


Specify the UIC by using standard UIC format as described in the OpenVMS 
Guide to System Security. 


ICONCATENATE (default) 

/INOCONCATENATE 

Creates one output file from multiple input files when you do not use the asterisk 
(*) or percent sign (%) wildcard characters in the output file specification. 

The /NOCONCATENATE qualifier generates multiple output files. A wildcard 
character in an input file specification results in a single output file consisting of 
the concatenation of all input files matching the file specification. 


Files from Files—11 On-Disk Structure Level 2 disks are concatenated in 
alphanumeric order; if you specify an asterisk (*) or percent sign (%) wildcard 
character in the file version field, files are copied in descending order by version 
number. Files from Files—11 On-Disk Structure Level 1 disks are concatenated in 
random order. 


/CONFIRM 

/NOCONFIRM (default) 

Controls whether a request is issued before each copy operation to confirm that 
the operation should be performed on that file. The following responses are valid: 


YES NO QUIT 
TRUE FALSE Ctrl/Z 
1 0 ALL 


You can use any combination of uppercase and lowercase letters for word 
responses. You can abbreviate word responses to one or more letters (for example, 
T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative 
answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, 

and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that 
you want to stop processing the command at that point. When you respond by 
entering ALL, the command continues to process but no further prompts are 
given. If you type a response other than one of those in the list, DCL issues an 
error message and redisplays the prompt. 
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/CONTIGUOUS 

/INOCONTIGUOUS 

Specifies that the output file must occupy contiguous physical disk blocks. 
By default, the COPY command creates an output file in the same format as 
the corresponding input file. Also, by default, if not enough space exists for 

a contiguous allocation, the COPY command does not report an error. If you 
copy multiple input files of different formats, the output file may or may not be 
contiguous. You can use the /CONTIGUOUS qualifier to ensure that files are 
copied contiguously. 


The /CONTIGUOUS qualifier has no effect when you copy files to or from tapes 
because the size of the file on tape cannot be determined until after it is copied to 
the disk. If you copy a file from a tape and want the file to be contiguous, use the 
COPY command twice: once to copy the file from the tape, and a second time to 
create a contiguous file. 


/CREATED (default) 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The 
/CREATED qualifier selects files based on their dates of creation. This qualifier is 
incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which 
also allow you to select files according to time attributes. If you specify none of 
these four time qualifiers, the default is the /CREATED qualifier. 


/EXCLUDE=(filespecf{....]) 

Excludes the specified files from the copy operation. You can include a directory 
but not a device in the file specification. The asterisk (*) and the percent sign 
(% ) wildcard characters are allowed in the file specification. However, you cannot 
use relative version numbers to exclude a specific version. If you specify only one 
file, you can omit the parentheses. 


/EXPIRED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /EXPIRED qualifier selects files according to their expiration dates. (The 
expiration date is set with the SET FILE/EXPIRATION_DATE command.) 
The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/EXTENSION=n 

Specifies the number of blocks to be added to the output file each time the file is 
extended. If you do not specify the /EXTENSION qualifier, the extension attribute 
of the corresponding input file determines the default extension attribute of the 
output file. 


/LOG 

/NOLOG (default) 

Controls whether the COPY command displays the file specifications of each file 
copied. 


When you use the /LOG qualifier, the COPY command displays the following for 
each copy operation: 


¢ The file specifications of the input and output files 


e The number of blocks or the number of records copied (depending on whether 
the file is copied on a block-by-block or record-by-record basis) 
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e The total number of new files created 


/MODIFIED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /MODIFIED qualifier selects files according to the dates on which they were 
last modified. This qualifier is incompatible with the /BACKUP, /CREATED, 
and /EXPIRED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time modifiers, the default is the 
/CREATED qualifier. 


/OVERLAY 

/INOOVERLAY (default) 

Requests that data in the input file be copied into the existing specified file, 
overlaying the existing data, rather than allocating new space for the file. The 
physical location of the file on disk does not change. However, for RMS indexed 
and relative files, if the output file has fewer blocks allocated than the input file, 
the copy fails giving an RMS-E-EOF error. 


The /OVERLAY qualifier is ignored if the output file is written to a non-file- 
structured device. 


/PROTECTION=(ownership[:access]|....]) 
Specifies protection for the output file. 


e Specify the ownership parameter as system (S), owner (QO), group (G), or 
world (W). 


¢ Specify the access parameter as read (R), write (W), execute (E), or delete 
(D). 


The default protection, including any protection attributes not specified, is that 
of the existing output file. If no output file exists, the current default protection 
applies. 


For more information on specifying protection codes, see the OpenVMS Guide to 
System Security. 


/READ_CHECK 
/NOREAD_CHECK (default) 
Reads each record in the input files twice to verify that it has been read correctly. 


/REPLACE 

/NOREPLACE (default) 

Requests that, if a file exists with the same file specification as that entered for 
the output file, the existing file is to be deleted. The COPY command allocates 
new space for the output file. In general, when you use the /REPLACE qualifier, 
include version numbers with the file specifications. By default, the COPY 
command creates a new version of a file if a file with that specification exists, 
incrementing the version number. The /NOREPLACE qualifier signals an error 
when a conflict in version numbers occurs. 


/SINCE[=time] 

Selects only those files dated after the specified time. You can specify time 

as absolute time, as combination of absolute and delta times, or as one of 
the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 
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For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


/TRUNCATE (default) 

/INOTRUNCATE 

Controls whether the COPY command truncates an output file at the end-of-file 
(EOF) when copying it. This operation can only be used with sequential files. 


By default, the actual size of the input file determines the size of the output file. 
If you select /NOTRUNCATE, the allocation of the i file determines the size 
of the output file. 


/VOLUME=n 

Places the output file on the specified relative volume number of a multivolume 
set. By default, the COPY command places the output file arbitrarily in a 
multivolume set. 


/WRITE_CHECK 

/NOWRITE_CHECK (default) 

Reads each record in the output file after it was written to verify that the record 
was copied successfully and that the file can be read subsequently without error. 


Note 


Some hardware devices, such as TK50 tape drives, verify data integrity 
as part of their hardware function. For devices such as these, you do 
not need to use /WRITE_CHECK. For information about which devices 
provide automatic write checking, consult your hardware documentation. 


Examples 


1. 


2. 


$ COPY TEST.DAT NEWTEST.DAT 


In this example, the COPY command copies the contents of the file TEST.DAT 
from the default disk and directory to a file named NEWTEST.DAT on the same 
disk and directory. If a file named NEWTEST:.DAT exists, the COPY command 
creates a new version of the file. 


$ COPY ALPHA.TXT TMP 
$ COPY ALPHA.TXT .TMP 


In this example, the first COPY command copies the file ALPHA.TXT into a 

file named TMP.TXT. The COPY command uses the file type of the input file to 
complete the file specification for the output file. The second COPY command 
creates a file named ALPHA.TMP. The COPY command uses the file name of the 
input file to name the output file. 


$ COPY/LOG TEST.DAT NEW.DAT;1/REPLACE 
$COPY-I-REPLACED, DBA0:[MAL]NEW.DAT;1 being replaced 
$COPY-S-COPIED, DBAO:[MAL]TEST.DAT;1 copied to DBAO:[MAL]NEW.DAT;1 (1 block) 


In this example, the /REPLACE qualifier requests that the COPY command 
replace an existing version of the output file with the new file. The first message 
from the COPY command indicates that it is replacing an existing file. The 
version number in the output file must be explicit; otherwise, the COPY command 
creates a new version of the file NEW.DAT. 
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4. 


8. 


9. 


$ COPY *.COM [MALCOLM.TESTFILES ] 


In this example, the COPY command copies the highest versions of files in 
the current default directory with the file type .COM to the subdirectory 
MALCOLM.TESTFILES. 


$ COPY/LOG *.TXT *.OLD 


$COPY-S-COPIED, DBAQ:[MAL]JA.TXT;2 copied to DBAQ:[MAL]A.OLD;2 (1 block) 
$COPY-S-COPIED, DBAQ:[MAL]B.TXT:2 copied to DBAQ:[MAL]B.OLD;2 (1 block) 
$COPY-S-COPIED, DBAQ:[MAL]G.TXT;2 copied to DBAQ:[MAL]G.OLD;2 (4 blocks) 


tCOPY-S-NEWFILES, 3 files created 


In this example, the COPY command copies the highest versions of files with file 
types .TXT into new files. Each new file has the same file name as an existing 
file, but a file type .OLD. The last message from the COPY command indicates 
the number of new files that have been created. 


$ COPY/LOG A.DAT,B.MEM C.* 

tCOPY-S-COPIED, DBAQ:[MALJA.DAT;5 copied to DBAQ:[MAL]C.DAT;11 (1 block) 
$COPY-S-COPIED, DBAQ:[MAL]B.MEM;2 copied to DBAQ:[MAL]C.MEM;24 (58 records) 
tCOPY-S-NEWFILES, 2 files created 


In this example, the two input file specifications are separated with a comma. 
The asterisk (*) wildcard character in the output file specification indicates that 
two output files are to be created. For each copy operation, the COPY command 
uses the file type of the input file to name the output file. 


$ COPY/LOG *.TXT TXT.SAV 

SCOPY-S-COPIED, DBAQ:[MAL]A.TXT;2 copied to DBAQ:[MAL]TXT.SAV;1 (1 block) 
%COPY-S-APPENDED, DBA0:(MAL]B.TXT;2 appended to DBAO:{MAL]TXT.SAV;1 (3 records) 
tCOPY-S-APPENDED, DBAQ:[MAL]G.TXT;2 appended to DBAO:{MAL]TXT.SAV;1 (51 records) 
%COPY-S-NEWFILES, 1 file created 


In this example, the COPY command copies the highest versions of all files with 
the file type TXT to a single output file named TXT.SAV. After the first input file 
is copied, the messages from the COPY command indicate that subsequent files 
are being appended to the output file. 


Note that, if you use the /NOCONCATENATE qualifier in this example, the 
COPY command creates one TXT.SAV file for each input file. Each TXT.SAV file 


has a different version number. 


$ COPY MASTER.DOC DBA1: [BACKUP] 


In this example, the COPY command copies the highest version of the file 
MASTER.DOC to the device DBA1. If no file named MASTER.DOC exists in 
the directory [BACKUP], the COPY command assigns the version number of 
the input file to the output file. You must have write (W) access to the directory 
[BACKUP] on device DBA1 for the command to work. 


$ COPY SAMPLE.EXE DALLAS: :DISK2:[000,000]SAMPLE.EXE/CONTIGUOUS 


In this example, the COPY command copies the file SAMPLE.EXE on the local 
node to a file with the same name at remote node DALLAS. The /CONTIGUOUS 
qualifier indicates that the output file is to occupy consecutive physical disk 
blocks. You must have write (W) access to the device DISK2 on remote node 
DALLAS for the command to work. 
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10. $ COPY *.* PRTLND::*.* 


In this example, the COPY command copies all files within the user directory at 
the local node to the remote node PRTLND. The new files have the same names 
as the input file. You must have write (W) access to the default directory on 
remote node PRTLND for the command to work. 


11. $ COPY BOSTON: :DISK2:TEST.DAT;5 
_To: DALLAS"SAM SECReturn": :DISKO: [MODEL.TEST ] TEST. DAT/ALLOCATION=50 


In this example, the COPY command copies the file TEST.DAT;5 on the device 
DISK2 at node BOSTON to a new file named TEST.DAT at remote node 
DALLAS. The /ALLOCATION qualifier initially allocates 50 blocks for the 

new file TEST.DAT at node DALLAS. The access control string SAM SECReturn 
is used to access the remote directory. 


12. $ MOUNT TAPED1: VOL025 ‘TAPE: 
$ COPY TAPE:*.* * 


In this example, the MOUNT command requests that the volume labeled VOL025 
be mounted on the magnetic tape device TAPED1 and assigns the logical name 
TAPE to the device. 


‘The COPY command uses the logical name TAPE as the input file specification, 
requesting that all files on the magnetic tape be copied to the current default disk 
and directory. All the files copied retain their file names and file types. 


13. $ ALLOCATE CR: 
_CR1: ALLOCATED 
$ COPY CR1: CARDS.DAT 
$ DEALLOCATE CR1: 


In this example, the ALLOCATE command allocates a card reader for exclusive 
use by the process. The response from the ALLOCATE command indicates the 
device name of the card reader, CR1. 


After the card reader is allocated, you can place a deck of cards in the reader and 
enter the COPY command, specifying the card reader as the input file. The COPY 
command reads the cards into the file CARDS.DAT. The end-of-file (EOF) in the 
card deck must be indicated with an EOF card (12-11-0-1-6-7-8-9 overpunch). 


The DEALLOCATE command relinquishes use of the card reader. 


14. $ COPY [SMITH]CATS.DIR [JONES] 
$ COPY [SMITH.CATS]*.* [JONES.CATS]*.* 


In this example, the COPY command creates the new empty directory 
[JONES.CATS] that is registered in the [JONES]CATS.DIR directory file. After 
the COPY command creates the new [JONES]CATS.DIR directory file, you can 
copy or create files in the [JONES.CATS] directory. 


The second COPY command in this example copies files from the [SMITH.CATS] 
directory to the [JONES.CATS] directory. 
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15. $ COPY [SMITH]CATS.DIR [SMITH]DOGS.DIR 


In this example, the COPY command creates the new empty directory file, called 
[SMITHIDOGS.DIR. Use this copy command to create a directory file that has 
the same attributes as the [SMITH]CATS.DIR file. This command example has 
the same effect as entering the command: 


$ CREATE/DIRECTORY [SMITH.DOGS] 


16. $ COPY [SMITH]CATS.DIR [SMITH.ANIMALS ] 
$ COPY [SMITH.CATS]*.* [SMITH.ANIMALS.CATS]*.* 
$ DELETE [SMITH.CATS]*.*; + 
$ SET PROTECTION=W=D CATS.DIR 
$ DELETE CATS.DIR; 
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In this example, the COPY command creates the new empty directory file called 
[SMITH.ANIMALS]CATS.DIR. The subsequent commands in this example then 
copy the files from the [SMITH.CATS] directory to the [SMITH.ANIMALS.CATS] 
directory, then delete the original CATS.DIR directory file. Because the 
CATS.DIR is a directory file, you must specify a protection code of delete (D) 
before you can delete the directory file. 
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COPY/FTP 


Transfers files between hosts with possibly dissimilar file systems over a TCP/IP 
connection by invoking the FTP utility. 


Format 
COPY/FTP  fromFile toFile 
Parameters 
fromFile 
Specifies the name of an existing file (the source file) to be copied. 
toFile 
Specifies the name of the output file (the destination file) into which the input file 
is copied. 
Description 


The COPY/FTP command copies files to and from remote nodes using the File 
Transfer Protocol (FTP). The services provided by this command are a subset 
of the architected features of FTP (see vendor documentation for usage of their 
supplied FTP program). 


For OpenVMS to OpenVMS Transfers 


If both machines support OpenVMS structured transfers, the /BINARY, 
/ASCII, and /FDL qualifiers will be ignored. The cooperating OpenVMS 
FTP client and server will automatically transfer the file with proper 
OpenVMS attributes. 


COPY/FTP commonly supports the asterisk wildcard character (*) in remote file 
specifications. 


Qualifiers 


/ANONYMOUS | 

Causes an anonymous access to the remote node or nodes. /ANONYMOUS is the 
default remote access. The password passed to the remote node should be in the 
form of “user@fullyqualifiednodename". 


/ASCIl 
Used to identify an ASCII file (text file). /ASCII is the default. 


/BINARY 
Required to identify binary files. 


/FDL 

This qualifier is optional. Causes interaction with an FDL (file definition 
language) file. If the file is being copied to the local OpenVMS system, a remote 
FDL file is sought and interpreted for the operation. If the file is being copied 
outside the local OpenVMS system, an FDL file is generated and copied in 
addition to the requested file. If the /FDL qualifier is specified and the vendor 
application does not support it, a warning message may be issued. 
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/LOG 
Displays a message at SYS$OUTPUT when a file is transferred. 


/NOSTRUVMS 
Used to explicitly disable the negotiation of STRU OpenVMS transfers. 
Otherwise, some servers will immediately abort when negotiating the feature. 


VERBOSE 

/NOVERBOSE 

Specifies whether all messages (including banner messages) are to be displayed 
on the terminal. By default, disables the display of the messages. 


1. $ COPY/FTP/FDL/ANON rms_indexed_file.idx remotehst5::"/public/rms.idx.file" 


This example transfers the OpenVMS RMS file rms_indexed_file.idx to the 

remote file public/rms.idx.file on remotehst5 over a TCP/IP connection. 
Access to the remote host is anonymous and an FLD file is generated and 
copied along with rms_indexed_file.idx. 
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Format 


Parameters 


Description 


Qualifiers 


Copies files from host to host over a TCP/IP connection by invoking the RCP 
utility. 


COPY/RCP _fromFile toFile 


fromFile 
Specifies the name of an existing file (the source file) to be copied. 


toFile 
Specifies the name of the output file (the destination file) into which the input file 
is copied. 


The COPY/RCP command copies one or more files (or directory trees) to or from a 
remote host using the RCP utility. 


The OpenVMS DCL commands for TCP/IP support the same remote file 
specification format as the DCL commands for DECnet network connections. 
Some implementations of the file transaction applications support file transfers in 
which both the source file and the destination file are remote file specifications. 


The full format for a remote file specification is as follows: 
node“username password account"::filename.ext 


If a file resides on a non OpenVMS system, enclose the name of the file in 
quotation marks. For example, to access a file named /wsr/users/user/Orders on 
a DEC OSF/1 node named U32, you would use the following format for the file 
specification: 


U32"user password"::"/usr/users/user/Orders" 


Unlike OpenVMS, UNIX systems support case-sensitive file specifications. 


/AUTHENTICATE 
Specifies that Kerberos authentication should be used for acquiring access to the 
remote node. 


/LOG 
Displays a message in SYS$OUTPUT when a file is transferred. 


/PRESERVE 
Preserves the file protection codes. 


/RECURSIVE 
Requests a subdirectory copy operation. 


/TRUNCATE=USERNAME 
Truncates the user name to 8 characters. 
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/USERNAME=username 


Optional qualifier that specifies the remote user name. The standard operation is 
to log in to a remote system using the same user name as at the local terminal. 
The command supports quoted parameters in the /USERNAME value. 


1. $ COPY/RCP local_file.c remotehst4"Smith smpw"::rem file.c 


This example copies local_file.c to rem_file.c on the remote host remotehst4 
over a TCP/IP connection. 


CREATE 


CREATE 
Creates a sequential disk file (or files). 

Format 
CREATE filespec{....] 

Parameter 
filespec{,...] 
Specifies the name of one or more input files to be created. Wildcard characters 
are not allowed. If you omit either the file name or the file type, the CREATE 
command does not supply any defaults. The file name or file type is null. If the 
specified file already exists, a new version is created. 

Description 


The CREATE command creates a new sequential disk file. In interactive mode, 
each separate line that you enter after you enter the command line becomes a 
record in the newly created file. To terminate the file input, press Ctrl/Z. 


When you enter the CREATE command from a command procedure file, the 
system reads all subsequent records in the command procedure file into the 
new file until it encounters a dollar sign ($) in the first position in a record. 
Terminate the file input with a line with a dollar sign in column 1 (or with the 
end of the command procedure). 


If you use an existing file specification with the CREATE command, the newly 
created file has a higher version number than any existing files with the same 
specification. 


If you use the CREATE command to create a file in a logical name search list, 
the file will only be created in the first directory produced by the logical name 
translation. 


Normally, the owner of the output file will be the same as the creator of the 
output file. However, if a user with extended privileges creates the output file, 
the owner will be the owner of the parent directory or any previous versions of 
the output file. 


Extended privileges include any of the following: 
e SYSPRV (system privilege) or BYPASS 
e System user identification codes (UICs) 


¢ GRPPRV (group privilege) if the owner of the parent directory (or previous 
version of the output file) is in the same group as the creator of the new 
output file 


e An identifier (with the resource attribute) representing the owner of the 
parent directory (or previous version of the output file) 
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Qualifiers 


/LOG 
/NOLOG (default) 
Displays the file specification of each new file created as the command executes. 


/OWNER_UIC=uic 
Requires SYSPRV (system privilege) privilege to specify a user 
identification code (UIC) other than your own. 


Specifies the UIC to be associated with the file being created. Specify the UIC by 
using standard UIC format as described in the OpenVMS User’s Manual. 


/PROTECTION=(ownership[:access]....]) 
Specifies protection for the file. 


¢ Specify the ownership parameter as system (S), owner (O), group (G), or 
world (W). 


e Specify the access parameter as read (R), write (W), execute (E), or delete 
(D). 


If you do not specify a value for each access category, or if you omit the 
/PROTECTION qualifier, the CREATE command applies the following protection 
for each unspecified category: 


File Already 
Exists? Protection Applied 


Yes | Protection of the existing file 
No Current default protection 


For more information on specifying protection codes, see the OpenVMS Guide to 
System Security. 


/VOLUME=n 
Places the file on the specified relative volume of a multivolume set. By default, 
the file is placed arbitrarily in a multivolume set. 


Examples 


1. $ CREATE MEET.TXT 
John, Residents in the apartment complex will hold their annual meeting 
this evening. We hope to see you there, Regards, Elwood 


The CREATE command in this example creates a text file named MEET.TXT 
in your default directory. The text file MEET.TXT contains the lines that 
follow until the Ctrl/Z. 


2. $ CREATE A.DAT, B.DAT 
Input line one for A.DAT... 
Input line two for A.DAT... 


Input line one for B.DAT... 
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Input line two for B.DAT... 


$ 


After you enter the CREATE command from the terminal, the system reads 
input lines into the sequential file A.DAT until Ctrl/Z terminates the first 
input. The next set of input data is placed in the second file, B.DAT. Again, 
Ctrl/Z terminates the input. 


$ FILE = FSSEARCH("MEET.TXT") 

$ IF FILE .EQS. "" 

$ THEN CREATE MEET.TXT 
John, Residents in the apartment complex will hold their annual meeting 
this evening. We hope to see you there, Regards, Elwood 

$ ELSE TYPE MEET.TXT 

$ ENDIF 

$ EXIT 


In this example, the command procedure searches the default disk and 
directory for the file MEET.TXT. If the command procedure determines:that 
the file does not exist it creates a file named MEET.TXT using the CREATE 
command. 
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CREATE/DIRECTORY 


Format 


Parameter 


Description 


Qualifiers 
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Creates one or more new directories or subdirectories. The /DIRECTORY qualifier 
is required. 


Requires write (W) access to the master file directory (MFD) to create 
a first-level directory. On a system volume, generally only users with a 
system user identification code (UIC) or the SYSPRV (system privilege) 
or BYPASS user privileges have write (W) access to the MFD to create a 
first-level directory. 


Requires write (W) access to the lowest level directory that currently 
exists to create a subdirectory. 


CREATE/DIRECTORY  directory-spec{....] 


directory-specJ....] 

Specifies the name of one or more directories or subdirectories to be created. The 
directory specification optionally can be preceded by a device name (and colon [:]). 
The default is the current default directory. Wildcard characters are not allowed. 
When you create a subdirectory, separate the names of the directory levels with 
periods (.). 


Note that it is possible to create a series of nested subdirectories with a single 
CREATE/DIRECTORY command. For example, [a.b.c] can be created, even 
though neither [a.b] nor [a] exists at the time the command is entered. Each 
subdirectory will be created, starting with the highest level and proceeding 
downward. 


The CREATE/DIRECTORY command creates new directories as well as 
subdirectories. Special privileges are needed to create new first-level directories. 
(See the restrictions noted above.) Generally, users have sufficient privileges to 
create subdirectories in their own directories. Use the SET DEFAULT command 
to move from one directory to another. 


/LOG 

/NOLOG (default) 

Controls whether the CREATE/DIRECTORY command displays the directory 
specification of each directory after creating it. 


/OWNER_UIC=option 
Requires SYSPRV (system privilege) privilege for a user identification 
code (UIC) other than your own. 


Specifies the owner UIC for the directory. The default is your UIC. You can 
specify the keyword PARENT in place of a UIC to mean the UIC of the parent 
(next-higher-level) directory. If a user with privileges creates a subdirectory, by 


‘default, the owner of the subdirectory will be the owner of the parent directory 


(or the owner of the MFD, if creating a main level directory). If you do not 
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CREATE/DIRECTORY 


specifiy the /OWNER_UIC qualifier when creating a directory, the command 

assigns ownership as follows: (1) if you specify the directory name in either 

alphanumeric or subdirectory format, the default is your UIC (unless you are 
privileged in which case the UIC defaults to the parent directory); (2) if you 
specify the directory in UIC format, the default is the specified UIC. 


Specify the UIC by using standard UIC format as described in the OpenVMS 
User’s Manual. 


/PROTECTION=(ownership[:access]|[,...]) 
Specifies protection for the directory. 


¢ Specify the ownership parameter as system (S), owner (QO), group (G), or 
world (W). 


e Specify the access parameter as read (R), write (W), execute (E), or delete 
(D). 


The default protection is the protection of the parent directory (the next-higher 
level directory, or the master directory for top-level directories) minus any delete 
(D) access. 


If you are creating a first-level directory, then the next-higher-level directory 
is the MFD. (The protection of the MFD is established by the INITIALIZE 
command.) 


For more information on specifying protection code, see the OpenVMS Guide to 
System Security. 


/VERSION_LIMIT=n 

Specifies the number of versions of any one file that can exist in the directory. 
If you exceed the limit, the system deletes the lowest numbered version. A 
specification of 0 means no limit. The maximum number of versions allowed is 
32,767. The default is the limit for the parent (next-higher-level) directory. 


When you change the version limit setting, the new limit applies only to files 
created after the setting was changed. New versions of files created before the 
change are subject to the previous version limit. 


/VOLUME=n 

Requests that the directory file be placed on the specified relative volume of a 
multivolume set. By default, the file is placed arbitrarily within the multivolume 
set. 


1. $ CREATE/DIRECTORY/VERSION LIMIT=2 $DISK1: [ACCOUNTS .MEMOS ] 


In this example, the CREATE/DIRECTORY command creates a subdirectory 
named MEMOS in the ACCOUNTS directory on $DISK1. No more than two 
versions of each file can exist in the directory. 


2. $CREATE/DIRECTORY/PROTECTION=(SYSTEM:RWCD,OWNER:RWCD,GROUP,WORLD) - 
_5[MALCOLM.SUB.HLP ] 


In this example, the CREATE/DIRECTORY command creates a subdirectory 
named [MALCOLM.SUB.HLP]. The protection on the subdirectory allows 
read (R), write (W), execute (E), and delete (D) access for the system and 
owner categories, but prohibits all access for the group or world categories. 
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3. 


$ CREATE/DIRECTORY DISK2: [MALCOLM] 


In this example, the CREATE/DIRECTORY command creates a directory 
named [MALCOLM] on the device DISK2. Special privileges are required to 
create a first-level directory. 


$ CREATE/DIRECTORY [MALCOLM. SUB] 
$ SET DEFAULT [MALCOLM. SUB] 


In this example, the CREATE/DIRECTORY command creates a subdirectory 
named [MALCOLM.SUB]. This directory file is placed in the directory named 
[MALCOLM]. The command SET DEFAULT [MALCOLM.SUB] changes the 
current default directory to this subdirectory. All files subsequently created 
are cataloged in [MALCOLM.SUB]. 


$ CREATE/DIRECTORY [FRED.SUB1.SUB2.SUB3] 


In this example, the CREATE/DIRECTORY command creates a top- 
level directory ([FRED]) and three subdirectories ([FRED.SUB1], 
[FRED.SUB1.SUB2], and [FRED.SUB1.SUB2.SUB3)). 


CREATE/FDL 


CREATE/FDL 


Invokes the Create/FDL utility, which uses the specifications in a File Definition 
Language (FDL) file to create a new, empty data file. The /FDL qualifier is 
required. For a complete description of the Create/FDL utility, see the OpenVMS 


Record Management Utilities Reference Manual. 


Format 
CREATE/FDL=fdl-filespec [filespec] 
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Format 


Parameter 


Description 


Qualifiers 
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Creates a new logical name table. The /NAME_TABLE qualifier is required. 
CREATE/NAME_TABLE _table-name 


table-name 

Specifies a string of 1 to 31 characters that identifies the logical name table you 
are creating. The string can include alphanumeric characters, the dollar sign 
($), and the underscore (_). This name is entered as a logical name in either 
the process directory logical name table (LNM$PROCESS_DIRECTORY) or the 
system directory logical name table (LNM$SYSTEM_DIRECTORY). 


The CREATE/NAME_TABLE command creates a new logical name table. 
The name of the table is contained within the LNM$PROCESS_DIRECTORY 
directory table if the table is process-private, and within the LNM$SYSTEM_ 
DIRECTORY directory table if the table is shareable. 


Every new table has a parent table, which determines whether the new table is 
process-private or shareable. To create a process-private table, use the /PARENT_ 
TABLE qualifier to specify the name of a process-private table (the process 
directory table). To create a shareable table, specify the parent as a shareable 
table. 


If you do not explicitly provide a parent table, the CREATE/NAME_TABLE 
command creates a process-private table whose parent is LNM$PROCESS_ 
DIRECTORY; that is, the name of the table is entered in the process directory. 


Every table has a size quota. The quota may either constrain the potential 
growth of the table or indicate that the table’s size can be virtually unlimited. 
The description of the /QUOTA qualifier explains how to specify a quota. 


To specify an access mode for the table you are creating, use the /USER_MODE, 

the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. If you specify 

more than one of these qualifiers, only the last one entered is accepted. If you do 
not specify an access mode, then a supervisor-mode table is created. 


To delete a logical name table, use the DEASSIGN command, specify the name of 
the table you want to delete, and use the /TABLE qualifier to specify the directory 
table where the name of the table was entered. 


For more information about logical name tables, see the OpenVMS System 
Manager’s Manual. 


/ATTRIBUTES[=(keyword{,...])] . 
Specifies attributes for the logical name table. If you specify only one keyword, 
you can omit the parentheses. If you do not specify the /ATTRIBUTES qualifier, 
no attributes are set. 


CREATE/NAME_TABLE 


You can specify the following keywords for attributes: 


CONFINE Does not copy the table name or the logical names contained in 
the table into a spawned subprocess; used only when creating 
a private logical name table. If a table is created with the 
CONFINE attribute, all names subsequently entered into the 
table are also confined. 


NO_ALIAS No identical names (either logical names or names of logical 
name tables) may be created in an outer (less privileged) mode 
in the current directory. If you do not specify the NO_ALIAS 
attribute, then the table may be “aliased” by an identical name 
created in an outer access mode. Deletes any previously created 
identical table names in an outer access mode in the same 
logical name table directory. 


SUPERSEDE Creates a new table that supersedes any previous (existing) 
table that contains the name, access mode, and directory 
table that you specify. The new table is created regardless 
of whether the previous table exists. (If you do not specify 
the SUPERSEDE attribute, the new table is not created if the 
previous table exists.) 

If you specify or accept the default for the qualifier /LOG, you 
receive a message indicating the result. 


/EXECUTIVE_MODE 
Requires SYSNAM (system logical name) privilege. 


Creates an executive-mode logical name table. If you specify executive mode, but 
do not have SYSNAM privilege, a supervisor-mode logical name table is created. 


/LOG (default) 

INOLOG | 

Controls whether an informational message is generated when the SUPERSEDE 
attribute is specified, or when the table already exists but the SUPERSEDE 
attribute is not specified. The default is the /LOG qualifier; that is, the 
informational message is displayed. 


/PARENT_TABLE=table 
Requires either create (C) access to the parent table and write (W) access 
to the system directory or the SYSNAM privilege. 


Specifies the name of the parent table. The parent table determines whether a 
table is private or shareable; it also determines the size quota of the table. If you 
do not specify a parent table, the default table is LNM$PROCESS_DIRECTORY. 
A shareable table has LNM$SYSTEM_DIRECTORY as its parent table. The 
parent table must have the same access mode or a higher level access mode than 
the one you are creating. 


/PROTECTION=(ownership[:access]|[....]) 
Applies the specified protection to shareable name tables. 


e Specify the ownership parameter as system (S), owner (O), group (G), or 
world (W). . 


e¢ Specify the access parameter as read (R), write (W), create (C), or delete 
(D). 
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For more information on specifying protection codes, see the OpenVMS Guide to 
System Security. | 


The /PROTECTION qualifier affects only shareable logical name tables; it does 
not affect process-private logical name tables. 


/QUOTA=number-of-bytes 

Specifies the size limit of the logical name table. The size of each logical name 
entered in the new table is deducted from this size limit. The new table’s 
quota is statically subtracted from the parent table’s quota holder. The parent 
table’s quota holder is the first logical name table encountered when working 
upward in the table hierarchy that has an explicit quota and is therefore its own 
quota holder. If the /QUOTA qualifier is not specified or the size limit is 0, the 
parent table’s quota holder becomes the new table’s quota holder and space is 
dynamically withdrawn from it whenever a logical name is entered in this new 
table. If the table has no quota holder and you specify /QUOTA=0, the table has 
unlimited quota. 


/SUPERVISOR_MODE (default) 
Creates a supervisor-mode logical name table. If you do not specify a mode, a 
supervisor-mode logical name table is created. 


/USER_MODE 
Creates a user-mode logical name table. If you do not explicitly specify a mode, a 
supervisor-mode logical name table is created. 


Note 


User-mode logical names are automatically deleted when invoking and 
exiting a command procedure. 


1. § CREATE/NAME_ TABLE TEST TAB 
$ SHOW LOGICAL TEST TAB 
$SHOW-S-NOTRAN, no translation for logical name TEST TAB 
$ SHOW LOGICAL/TABLE=LNM$PROCESS_ DIRECTORY TEST TAB 


In this example, the CREATE/NAME_TABLE command creates a new table 
called TEST_TAB. By default, the name of the table is entered in the process 
directory. The first SHOW LOGICAL command does not find the name 
TEST_TAB because it does not, by default, search the process directory table. 
You must use the /TABLE qualifier to request that the process directory be 
searched. 


2. $ CREATE/NAME TABLE/ATTRIBUTES=CONFINE EXTRA 
$ DEFINE/TABLE=EXTRA MYDISK DISK4: 
$ DEFINE/TABLE=LNM$PROCESS DIRECTORY LNMSFILE DEV - 
$ EXTRA, LNMS$PROCESS, LNMS$JOB, LNM$GROUP, LNMSSYSTEM 
$ TYPE MYDISK: [COHEN ]EXAMPLE1.LIS 


This example creates a new logical name table called EXTRA that is created 
with the CONFINE attribute. Therefore, the EXTRA table and the names it 
contains will not be copied to subprocesses. 
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Next, the logical name MYDISK is placed into the table EXTRA. To use 

the name MYDISK in file specifications, you must make sure that the table 
EXTRA is searched when RMS parses file specifications. To do this, you 
can define a process-private version of the logical name LNM$FILE_DEV 

to include the name EXTRA as one of its equivalence strings. (The system 
uses LNM$FILE_DEV to determine the tables to search during logical name 
translation for device or file specifications, and will use the process-private 
version of the logical name before using the default system version.) After 
you define LNM$FILE_DEV, the system searches the following tables during 
logical name translation: EXTRA, your process table, your job table, your 
group table, and the system table. Now, you can use the name MYDISK in a 
file specification and the equivalence string DISK4 will be substituted. 
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Parameter 


Description 
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Creates a window that emulates another terminal type. 


Note 


At present, only DECterm windows are available with this command. 


CREATE/TERMINAL [commanda-string] 


command-string 

Specifies a command string that is to be executed in the context of the created 
subprocess. You cannot specify this parameter with the /DETACH or the 
/NOPROCESS qualifier. The CREATE/TERMINAL command is used in much the 
same way as the SPAWN command. 


The CREATE/TERMINAL command creates a subprocess of your current process. 
When the subprocess is created, the process-permanent open files and any image 
or procedure context are not copied from the parent process. The subprocess is 
set to command level 0 (DCL level with the current prompt). 


If you do not specify the /PROCESS qualifier, the name of this subprocess is 
composed of the same base name as the parent process and a unique number. 
For example, if the parent process name is SMITH, the subprocess name can be 
SMITH_1, SMITH_2, and so on. 


The LOGIN.COM file of the parent process is not executed for the subprocess, 
because the context is copied separately, allowing quicker initialization of the 
subprocess. When the /WAIT qualifier is in effect, the parent process remains in 


hibernation until the subprocess terminates and returns control to the parent by 
using the ATTACH command. 


You should use the LOGOUT command to terminate the subprocess and return 
to the parent process. You can also use the ATTACH command to transfer control 
of the terminal to another process in the subprocess tree, including the parent 
process. (The SHOW PROCESS/SUBPROCESS command displays the process in 
the subprocess tree and points to the current process.) 


Qualifiers 


CREATE/TERMINAL 


Note 


Because a tree of subprocesses can be established using the CREATE 
/TERMINAL command, you must be careful when terminating any 

- process in the tree. When a process is terminated, all the subprocesses 
below that point in the tree are automatically terminated. For example, 
the SPAWN/NOWAIT CREATE/TERMINAL command creates a 
subprocess that exits as soon as the DECterm window is created. Once 
this process exits, the DECterm window disappears. Instead, use the 
SPAWN/NOWAIT CREATE/TERMINAL/WAIT command to allow the 
process to continue. 


Qualifiers with the CREATE/TERMINAL command must directly follow the 
command verb. The command-string parameter begins after the last qualifier 
and continues to the end of the command line. 


/APPLICATION_KEYPAD 

Sets the APPLICATION_KEYPAD terminal characteristic in the created terminal 
window. If the /APPLICATION_KEYPAD or the /NUMERIC_KEYPAD qualifier 
is not specified, the default is to inherit the characteristic from the parent. (See 
also /NUMERIC_KEYPAD.) 


/BIG_FONT 

Specifies that the big font (as specified in resource files) be selected when the 
created terminal window is initialized. It is an error to specify the /BIG_FONT 
qualifier in combination with the /LITTLE_FONT qualifier. If you do not specify 
either the /BIG_FONT or the /LITTLE_FONT qualifier, the initial font is the big 
font. 


/BROADCAST 

/NOBROADCAST 

Determines whether the terminal window is created with broadcast messages 
enabled. If neither qualifier is specified, the created terminal window inherits the 
broadcast characteristic of the parent. 


/CARRIAGE_CONTROL 

/NOCARRIAGE_CONTROL 

Determines whether carriage-return and line-feed characters are prefixed to 
the subprocess’s prompt string. By default, the CREATE/TERMINAL command 
copies the current setting of the parent process. The CARRIAGE_CONTROL 
qualifier is used only with the (NODETACH qualifier. 


/CLl=cli-filespec 

/NOCLI 

Specifies the name of a command language interpreter (CLI) to be used by the 
subprocess. The default CLI is the same as that of the parent process (defined in 
SYSUAF). If you specify the /CLI qualifier, the attributes of the parent process are 
copied to the subprocess. The CLI you specify must be located in SYS$SYSTEM 
and have the file type EXE. This qualifier is used only with the /NODETACH 
qualifier. 
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/CONTROLLER=filespec 

Specifies the name of the terminal window controller image. This name allows 
the CREATE/TERMINAL command to create a window on a variant controller, 
such as for a language not supported by the base product. For a DECterm 
window, the default is SYS$SYSTEM:DECW$TERMINAL.EXE. The device and 
directory default to SYS$SYSTEM and the file type defaults to EXE. 


Note 


The “name” field of the file name as returned by $PARSE is 

used to form the mailbox logical name. For example, if the file 

“name” is DECW$TERMINAL, the mailbox logical name will be 
DECW$TERMINAL_MAILBOX_node::0.0. For backward compatibility, 
the controller also defines a logical name DECW$DECTERM_MAILBOX_ 
host::0.0 to point to the same mailbox. 


/DEFINE_LOGICAL=({logname, TABLE=tablename} [....]) 

Specifies one or more logical names that are set to the name of the created 
pseudo terminal device. Each element in the list is either a logical name or 
TABLE= followed by the name of a logical name table in which all subsequent 
logical names will be entered. The default is the process logical name table. 


/DETACH 

/NODETACH (default) 

Determines whether the created terminal process is detached or a subprocess of 
the current process. The /DETACH qualifier cannot be used with the command- 
string parameter. 


/DISPLAY=display-name 
Specifies the name of the display on which to create the terminal window. If this 
parameter is omitted, the DECW$DISPLAY logical name is used. 


[ESCAPE 

INOESCAPE 

Sets or clears the ESCAPE characteristic of the created terminal window. The 
default is to inherit the characteristic of the parent. 


/FALLBACK 

/NOFALLBACK 

Sets or clears the FALLBACK characteristic of the created terminal window. The 
default is to inherit the characteristic of the parent. 


/HOSTSYNC (default) 

/INOHOSTSYNC 

Sets or clears the HOSTSYNC characteristic of the created terminal window. The 
default is to inherit the characteristic of the parent. 


ANPUT=filespec 

Specifies an alternate input file or device to use as SYS$INPUT for the new 
process. The default is to use the created terminal window for input. This 
qualifier can be used with or without the /DETACH qualifier. 
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[INSERT 

Creates the terminal window with insert mode as the default for line editing. 
If the /INSERT or the /OVERSTRIKE qualifier is not specified, the default is to 
inherit the characteristic from the parent. (See also /OVERSTRIKE.) 


/KEYPAD (default) 

/NOKEYPAD 

Determines whether keypad definitions and the current keypad state are copied 
from the parent process. This qualifier is used only with the /NODETACH 
qualifier. 


/LINE_EDITING 

/NOLINE_EDITING 

Determines whether the terminal window is created with line editing enabled. 
If neither qualifier is specified, the created terminal window inherits the line 
editing characteristic of the parent. 


/LITTLE_FONT 

Specifies that the little font (as specified in resource files) be selected when the 
created terminal window is initialized. It is an error to specify the /LITTLE_ 
FONT qualifier in combination with the /BIG_FONT qualifier. If you do not 
specify either the /BIG_FONT or the /LITTLE_FONT qualifier, the initial font is 
the big font. 


/LOGGED_IN (default) 

/INOLOGGED_IN 

Determines whether a prompt for a user name and password are supplied 
(/NOLOGGED_IN) or the created terminal window is logged in automatically 
(/(LOGGED_IN). This qualifier is used only with the /DETACH qualifier. 


/LOGICAL_NAMES (default) 

/NOLOGICAL_NAMES 

Determines whether the created terminal window inherits the parent’s logical 
names. This qualifier is used only with the /NODETACH qualifier. 


/INOTIFY 

/NONOTIFY (default) 

Determines whether a notification message is broadcast to the parent when the 
created terminal window exits. This qualifier is used only with the /NODETACH 
qualifier. 


/NUMERIC_KEYPAD 

Sets the NUMERIC_KEYPAD terminal characteristic in the created terminal 
window. If the /NUMERIC_KEYPAD or the /APPLICATION_KEYPAD qualifier 
is not specified, the default is to inherit the characteristic from the parent. (See 
also /APPLICATION_KEYPAD.) 


/OVERSTRIKE 

Creates the terminal window with overstrike mode as the default for line editing. 
If the /OVERSTRIKE or the /INSERT qualifier is not specified, the default is to 
inherit the characteristic from the parent. (See also /INSERT.) 


/PASTHRU 

/NOPASTHRU 

Sets or clears the PASTHRU characteristic in the created terminal window. The 
default is to inherit the characteristic of the parent. 
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/PROCESS (default) 

/PROCESS=process-name 

/NOPROCESS 

Specifies the name of the process or subprocess to be created. The /NOPROCESS 
qualifier causes a window to be created without a process. You can log in from 
this window. 


If you specify the /PROCESS qualifier without a process name, a unique process 
name is assigned with the same base name as the parent process and a unique 
number. The default process name format is username_n. If you specify a process 
name that already exists, an error message is displayed. This qualifier is used 
with either the /DETACH or the /NODETACH qualifier. 


/PROMPT=prompt 
Specifies the prompt string of.the created terminal window. This qualifier is used 
only with the /NODETACH qualifier. 


/READSYNC 

/NOREADSYNC 

Sets or clears the READSYNC terminal characteristic in the created terminal 
window. The default is to inherit the characteristic from the parent. 


/RESOURCE_FILE=filespec 

Specifies that the created terminal window use the resource file “filespec” instead 
of the default resource file. DECW$USER_DEFAULTS:DECW$TERMINAL._ 
DEFAULT.DAT. 


/SYMBOLS (default) 

/NOSYMBOLS 

Determines whether the subprocess inherits the parent’s DCL symbols. This 
qualifier is used only with the /NODETACH qualifier. 


/TABLE=command-table 
Specifies the name of an alternate command table to be used by the subprocess. 
This qualifier is used only with the /(NODETACH qualifier. 


ITTSYNC 

/INOTTSYNC 

Sets or clears the TTSYNC terminal characteristic in the created terminal 
window; the default is to inherit the characteristic of the parent. 


/TYPE_AHEAD 

/INOTYPE_AHEAD 

Sets or clears the TYPE_AHEAD terminal characteristic in the created terminal 
window. The default is to inherit the characteristic of the parent. 


WAIT 

/NOWAIT (default) 

Requires that you wait for the subprocess to terminate before you enter another 
DCL command. The /NOWAIT qualifier allows you to enter new commands while 
the subprocess is running. This qualifier is used only with the /NODETACH 
qualifier. 


Example 
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/WINDOW_ATTRIBUTES=(parameter [,...]) 
Specifies initial attributes for the created terminal window to override the 
defaults read from the resource file. These parameters include: 


Parameter 


BACKGROUND 
FOREGROUND 
WIDTH 
HEIGHT 
X_POSITION 
Y_POSITION 
ROWS 


COLUMNS 


INITIAL_STATE 
TITLE 
ICON_NAME 
FONT 


Description 


The background color. 

The foreground color. 

The width, in pixels. 

The height, in pixels. 

The x-position, in pixels. 

The y-position, in pixels. 

The number of rows in the window, in character cells. If 
the Auto Resize Window option is enabled, the ROWS and 


COLUMNS parameters override the size specified by the 
WIDTH and HEIGHT parameters. 


The number of columns in the window, in character cells. If 
the Auto Resize Window option is enabled, the ROWS and 
COLUMNS parameters override the size specified by the 
WIDTH and HEIGHT parameters. . 

The initial state of the window, either ICON or WINDOW. 

A character string specifying the window title. 

A character string specifying the window icon name. 

The name of the font to be used in the window. If you specify 
the /LITTLE_FONT qualifier, or omit both the /LITTLE_ 
FONT and /BIG_FONT qualifiers, this overrides the name 
of the little font that is set in the resource files; otherwise it 
overrides the name of the big font. The font name can be a 
logical name, and it can be (but does not have to be) the base 
font in a complete font set. 


$ CREATE/TERMINAL=DECTERM/DETACH - 
$ /DISPLAY=MYNODE::0 - 


$ ROWS=36, - 
$ COLUMNS=80, - 


$ /WINDOW_ATTRIBUTES=( - 


$ TITLE="REMOTE TERMINAL", - 


_5 ICON_NAME="REMOTE TERMINAL" ) 


In this example, the command creates a detached process in a DECterm window 
on node MYNODE:: that is 36 rows by 80 columns and has its title and icon 
name set to “Remote terminal”. 


$ CREATE/TERMINAL=DECTERM - 


$ /NOPROCESS - 


s- /DEFINE_LOGICAL=(TABLE=LNM$GROUP , DBGSINPUT , DBGSOUTPUT ) 


In this example, the command creates a DECterm with no associated process. 
The command defines DBG$INPUT and DBG$OUTPUT in the group table as the 
new terminal for the purposes of debugging a problem with a detached process 
that is subsequently created. 
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Format 


Parameter 


Qualifier 


Examples 
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Makes an allocated device available to other processes (but does not deassign 
any logical name associated with the device). DEALLOCATE does not deallocate 
devices that are in use. 


DEALLOCATE device-namef:] 


device-name[:] 

Name of the device to be deallocated. The device name can be a physical device 
name or a logical name that is not in use. On a physical device name, the 
controller defaults to A and the unit to 0. This parameter is incompatible with 
the /ALL qualifier. 


/ALL 
Deallocates all devices currently allocated by your process that are not in use. 
This qualifier is incompatible with the device-name parameter. 


1. $ DEALLOCATE DMB1: 


In this example, the DEALLOCATE command deallocates unit 1 of the 
RKO6/RKO07 devices on controller B. 


2. $ ALLOCATE MT; TAPE 
tDCL-I-ALLOC, MTB1: allocated 


$ DEALLOCATE TAPE: 


In this example, the ALLOCATE command requests that any magnetic tape 
drive be allocated and assigns the logical name TAPE to the device. The 
response to the ALLOCATE command indicates the successful allocation of 
the device MTB1. The DEALLOCATE command specifies the logical name 
TAPE to release the tape drive. 


3. $ DEALLOCATE/ALL 


In this example, the DEALLOCATE command deallocates all devices that are 
currently allocated. 


DEASSIGN 


DEASSIGN 


Format 


Parameter 


Description 


Cancels a logical name assignment that was made with one of the following 
commands: ALLOCATE, ASSIGN, DEFINE, or MOUNT. The DEASSIGN 
command also deletes a logical name table that was created with the CREATE 
/NAME_TABLE command. 


DEASSIGN _[logical-name{[:]] 


logical-name{[:] . 

Specifies the logical name to be deassigned. Logical names can have from 

1 to 255 characters. If the logical name contains any characters other than 
alphanumerics, dollar signs ($), or underscores (_), enclose it in quotation marks 
(“”). The logical-name parameter is required unless you use the /ALL qualifier. 


If the logical-name parameter ends with a colon (:), the command interpreter 
ignores the colon. (Note that the ASSIGN and ALLOCATE commands remove 
a trailing colon, if present, from a logical name before placing the name in a 
logical name table.) If a colon is present in the logical name, you must type two 
colons in the logical-name parameter of the DEASSIGN command (for example, 
DEASSIGN FILE::). 


To delete a logical name table, specify the table name as the logical-name 
parameter. You must also use the /TABLE qualifier to indicate the logical name 
directory table where the table name is entered. . 


The DEASSIGN command cancels a logical name assignment that was made with 
one of the following commands: ALLOCATE, ASSIGN, DEFINE, or MOUNT. 
The DEASSIGN command also deletes a logical name table that was created 
with the CREATE/NAME_TABLE command. You can use the /ALL qualifier with 
DEASSIGN to cancel all logical names in a specified table. If you use the /ALL 


- qualifier and do not specify a table, then all names in the process table (except 


names created by the command interpreter) are deassigned; that is, all names 
entered at the indicated access mode or an outer access mode are deassigned. 


To specify the logical name table from which you want to deassign a logical 
name, use the /PROCESS, the /JOB, the /GROUP, the /SYSTEM, or the /TABLE 
qualifier. If you enter more than one of these qualifiers, only the last one entered 
is accepted. If entries exist for the specified logical name in more than one logical 
name table, the name is deleted from only the last logical name table specified on 
the command line. If you do not specify a logical name table, the default is the 
/TABLE=LNM$PROCESS qualifier. 


To delete a shareable logical name, you need write (W) access to the logical name 
table. To delete a shareable logical name table, you need write (W) access to the 
parent table and delete (D) access to the target logical name table. __ 
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To specify the access mode of the logical name you want to deassign, use the 
/USER_MODE, the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. 
If you enter more than one of these qualifiers, only the last one is accepted. If 
you do not specify a mode, the DEASSIGN command deletes a supervisor-mode 
name. When you deassign a logical name, any identical names created with outer 
access modes in the same logical name table are also deleted. 


You must have SYSNAM (system logical name) privilege to deassign an executive- 
mode logical name. 


If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM 
privilege, then the DEASSIGN command ignores the qualifier and attempts to 
deassign a supervisor-mode logical name. 


All process-private logical names and logical name tables are deleted when you 
log out of the system. User-mode entries within the process logical name table 
are deassigned when any image exits. The logical names in the job table, and the 
job table itself, are deleted when you log off the system. 


Names in all other shareable logical name tables remain there until they are 
explicitly deassigned, regardless of whether they are user-, supervisor-, or 
executive-mode names. You must have write (W) access to a shareable logical 
name table to delete any name in that table. 


If you delete a logical name table, all the logical names in the table are also 
deleted. Also, any descendant tables are deleted. To delete a shareable logical 
name table, you must have delete (D) access to the table. 


/ALL 

Deletes all logical names in the same or an outer (less privileged) access 
mode. If no logical name table is specified, the default is the process table, 
LNM$PROCESS. If you specify the /ALL qualifier, you cannot enter a logical- 
name parameter. 


/EXECUTIVE_MODE 
Requires SYSNAM (system logical name) privilege to deassign executive- 
mode logical names. 


Deletes only entries that were created in the specified mode or an outer (less 
privileged) mode. If you do not have SYSPRV (system privilege) privilege for 
executive mode, a supervisor-mode operation is assumed. 


/GROUP 
Requires GRPNAM (group logical name) or SYSPRV privilege to delete 
entries from the group logical name table. 


Indicates that the specified logical name is in the group logical name table. The . 
/GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier. 


/JOB 

Indicates that the specified logical name is in the jobwide logical name table. The 
/JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier. If you do . 
not explicitly specify a logical name table, the default is the /PROCESS qualifier. 


DEASSIGN 


You should not deassign jobwide logical name entries that were made by the _ 
system at login time, for example, SYS$LOGIN, SYS$LOGIN_DEVICE, and 
SYS$SCRATCH. However, if you assign new equivalence names for these logical 
names (that is, create new logical names in outer access modes), you can deassign 
the names you explicitly created. 


/PROCESS (default) 
Indicates that the specified logical name is in the process logical name able: The 
/PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier. 


You cannot deassign logical name table entries that were made by the command 
interpreter, for example, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR. 
However, if you assign new equivalence names for these logical names (that 

is, you create new logical names in outer access modes), you can deassign the 
names you explicitly created. 


/SUPERVISOR_MODE (default) 

Deletes entries in the specified logical name table that were created in supervisor 
mode. If you specify the /SSUPERVISOR_MODE qualifier, the DEASSIGN 
command also deassigns user-mode entries with the same name. 


ISYSTEM 
Indicates that the specified logical name is in the system logical name table. The 
/SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier. 


/TABLE=name 

Specifies the table from which the logical name is to be deleted. Defaults to 
LNM$PROCESS. The table can be the process, group, job, or system table, one 
of the directory tables, or the name of a user-created table. (The process, job, 
group, and system logical name tables should be referred to by the logical names 
LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, respectively.) 


The /TABLE qualifier also:can be used to delete a logical name table. To delete a 
process-private table, enter the following command: 


$ DEASSIGN/ TABLE=LNMS$PROCESS DIRECTORY table-name 
To delete a shareable table, enter the following command: 
$ DEASSIGN/ TABLE=LNM$SYSTEM DIRECTORY table-name 


To delete a shareable logical name table, you must have delete (D) access to the 
table or write (W) access to the directory table in which the name of the shareable 
table is cataloged. 


If you do not explicitly specify the /TABLE qualifier, the default is the 
/TABLE=LNM$PROCESS qualifier. 


/USER_MODE 

Deletes entries in the process logical name table that were created in user mode. 
If you specify the /USER_MODE qualifier, the DEASSIGN command can deassign 
only user-mode entries. Also, user-mode logical names are automatically deleted 
when invoking and exiting a command procedure. 
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$ DEASSIGN MEMO 


The DEASSIGN command in this example deassigns the process logical name 
MEMO. 


$ DEASSIGN/ALL 


The DEASSIGN command in this example deassigns all process logical names 
that were created in user and supervisor mode. This command does not, 
however, delete the names that were placed in the process logical name table 
in executive mode by the command interpreter (for example, SYS$INPUT, 
SYS$OUTPUT, SYS$ERROR, SYS$DISK, and SYS$COMMAND). 


$ DEASSIGN/TABLE=LNM$PROCESS DIRECTORY TAX 


The DEASSIGN command in this example deletes the logical name table 
TAX, and any descendant tables. When you delete a logical name table, 
you must specify either the /TABLE=LNM$PROCESS_DIRECTORY or the 
/TABLE=LNM$SYSTEM_DIRECTORY qualifier, because the names of all 
tables are contained in these directories. 


$ ASSIGN USER DISK: COPY 
$ DEASSIGN COPY 


The ASSIGN command in this example equates the logical name COPY with 
the device USER_DISK and places the names in the process logical name 
table. The DEASSIGN command deletes the logical name. 


$ DEFINE SWITCH: TEMP 
$ DEASSIGN SWITCH:: 


The DEFINE command in this example places the logical name SWITCH: in 
the process logical name table. The trailing colon is retained as part of the 
logical name. Two colons are required on the DEASSIGN command to delete 
this logical name because the DEASSIGN command removes one trailing 
colon, and the other colon is needed to match the characters in the logical 
name. 


$ ASSIGN/TABLE=LNM$SGROUP DBAl: GROUP_DISK 
$ DEASSIGN/PROCESS/GROUP GROUP_DISK 


The ASSIGN command in this example places the logical name GROUP_ 
DISK in the group logical name table. The DEASSIGN command specifies 
conflicting qualifiers; because the /GROUP qualifier is last, the name is 
successfully deassigned. 


$ ASSIGN DALLAS::USER_DISK: DATA 


$ DEASSIGN DATA 


The ASSIGN command in this example associates the logical name DATA 
with the device specification USER_DISK on remote node DALLAS. 
Subsequent references to the logical name DATA result in references to 
the disk on the remote node. The DEASSIGN command cancels the logical 
name assignment. 


DEASSIGN/QUEUE 


DEASSIGN/QUEUE 


Format 


Parameter 


Description 


Example 


Deassigns a logical queue from a printer or terminal queue and stops the logical 
queue. Cannot be used with batch queues. 


Requires manage (M) access to the queue. 
DEASSIGN/QUEUE _logical-queue-name{[:] 


logical-queue-name[:] 
Specifies the name of the logical queue that you want to deassign from a specific 
printer or terminal queue. 


Once you enter the DEASSIGN/QUEUE command, the jobs in the logical queue 
remain pending until the queue is reassigned to another printer queue or device 
with the ASSIGN/QUEUE command. 


$ ASSIGN/QUEUE LPAO ASTER 


$ DEASSIGN/QUEUE ASTER 
$ ASSIGN/MERGE LPBO ASTER 


The ASSIGN/QUEUE command in this example associates the logical queue 
ASTER with the print queue LPAO. Later, you deassign the logical queue with 
the DEASSIGN/QUEUE command. The ASSIGN/MERGE command reassigns 
the jobs from ASTER to the print queue LPBO. 
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DEBUG 


Format 


Qualifiers 


Examples 
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Invokes the OpenVMS Debugger after program execution is interrupted by 
Ctrl/Y, but only if the /NOTRACEBACK qualifier was not specified with the 
LINK command when the program was linked. For a complete description of the 
OpenVMS Debugger, see the OpenVMS Debugger Manual. 


To get help on debugger commands from DCL level, type the following command: 
$ HELP/LIBRARY=SYSSHELP : DBGSHELP 


DEBUG 


/KEEP 

Invokes the Kept Debugger. The Kept Debugger includes a Run/Rerun capability 
that allows you to debug an image multiple times or debug a series of distinct 
images without exiting the debugger. 


Issuing the DEBUG/KEEP command is the only way to invoke the Kept 
Debugger. 


/RESUME (default) 

Reinvokes the non-Kept Debugger after a Ctrl/Y key sequence has interrupted 
the execution of a program you are debugging. (The interrupted program must 
not have been linked with a /NOTRACEBACK qualifier on the LINK command.) 


If you issue the DEBUG/RESUME command without a previous Ctrl/Y key 
sequence, no action occurs. Use the RUN program-name command to invoke the 
non-Kept Debugger. 


1. $ FORTRAN/DEBUG/NOOPTIMIZE WIDGET 
$ LINK/DEBUG WIDGET 
$ RUN/NODEBUG WIDGET 


NAME: 
NAME: 
NAME: 
“Y 
$ DEBUG 


[ Debugger Banner and Version ] 


%DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET 
DBG> 


The FORTRAN and LINK commands both specify the (DEBUG qualifier to 
compile the program WIDGET.FOR with debugger symbol table information 
and to include the debugger in the image file. The RUN command begins 
execution of the image WIDGET.EXE, which loops uncontrollably. Ctrl/Y 
interrupts the program, and the DEBUG command gives control to the 
debugger. 


DECK 


Format 


Description 


Qualifier 


DECK 


Marks the beginning of an input stream for a command or program. 
DECK 


The DECK command marks the data that follows it as input for a command or 
program. The DECK command can be used only after a request to execute a 
command or program that requires input data. 


In command procedures, this command is required when the first nonblank 
character in any data record in the input stream is a dollar sign. Also in 
command procedures, the DECK command must be preceded by a dollar sign; the 
dollar sign must be in the first character position (column 1) of the input record. 


The DECK command defines an end-of-file (EOF) indicator only for a single data 
stream. Using the DECK command enables you to place data records beginning 
with dollar signs in the input stream. You can place one or more sets of data in 
the input stream following a DECK command, if each is terminated by an EOF 
indicator. 


After an EOF indicator specified with the /DOLLARS qualifier is encountered, 
the EOF indicator is reset to the default, that is, to any record beginning with 
a dollar sign. The default is also reset if an actual EOF indicator occurs for the 
current command level. 


/DOLLARS[=string] 

Sets the EOF indicator to the specified string of 1 to 15 characters. Specify a 
string if the input data contains one or more records beginning with the string 
$EOD. Enclose the string in quotation marks (“ ”) if it contains literal lowercase 
letters, multiple blanks, or tabs. If you do not specify (DOLLARS or if you specify 
/DOLLARS without specifying a string, you must use the EOD command to signal 
the end-of-file (EOF). 
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Examples 


Input Stream ‘\ 
for \ 


Program A ‘\\._[§ PRINT SUMMARY.DAT 


$ EOD 
Me $ 99.50 
$ 86.42 
$ RUN A 
$ FORTRAN A ; 


“F 


In this example, the FORTRAN and LINK commands compile and link 
program A. When the program is run, any data the program reads from the 
logical device SYS$INPUT is read from the command stream. The DECK 
command indicates that the input stream can contain dollar signs in column 
1 of the record. The EOD command signals end-of-file (EOF) for the data. 
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DECK 


$ @TEST 


‘\ |$ PRINT RUNTEST.OUT 









$ RUN READFILE 


$ ASSIGN RUNTEST.OUT 
OUTFILE 


. $ ASSIGN SYS$INPUT 
\ INFILE 


\. | $ DECK/DOLLARS="%" 
$ CREATE TEST.COM 


a | 


G4) Input stream for CREATE command. 
(2) Input stream for program READFILE. 
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The CREATE command in this example creates the command procedure file 
TEST.COM from lines entered into the input stream. The DECK/DOLLARS 
command indicates that the percent sign (%) is the EOF indicator for the 
CREATE command. This allows the string $EOD to be read as an input 
record, signaling the end of the input for the RUN command. 
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Format 


Parameters 
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Associates an equivalence name with a logical name. 
DEFINE logical-name equivalence-namef{....] 


logical-name 
Specifies the logical name string, which is a character string containing from 1 to 
255 characters. The following rules apply: 


e Ifyou specify an existing logical name, the new equivalence names replace 
the existing equivalence name. 


e Ifthe logical name is to be entered into the process or system directory logical 
name tables (LNM$PROCESS_DIRECTORY, LNM$SYSTEM_DIRECTORY), 
then the name can only have from 1 to 31 alphanumeric characters, including 
the dollar sign ($) and underscore (_). 


e Ifyou specify a colon (:) at the end of a logical name, the DEFINE command 
saves the colon as part of the logical name. (This is in contrast to the ASSIGN 
command, which removes the colon before placing the name in a logical name 
table.) By default, the logical name is placed in the process logical name 
table. 


e Ifthe string contains any characters other than uppercase alphanumerics, the 
dollar sign, or the underscore character, enclose the string in quotation marks 
(“”). Use two sets of quotation marks (““””) to denote actual quotation 
marks. When you enclose a name in quotation marks, the case of alphabetic 
characters is preserved. 


equivalence-name{,...] 
Specifies a character string containing from 1 to 255 characters. The following 
rules apply: 


e Ifthe string contains any characters other than uppercase alphanumerics, 
the dollar sign, or the underscore character, enclose the string in quotation 
marks. Use two sets of quotation marks to denote an actual quotation mark. 
Specifying more than one equivalence name for a logical name creates a 
search list. 


¢ When you specify an equivalence name that will be used as a file specification, 
you must include the punctuation marks (colons, brackets, periods) that would 
be required if the equivalence name were used directly as a file specification. 
Therefore, if you specify a device name as an equivalence name, you must 
terminate the equivalence name with a colon. 


The DEFINE command allows you to assign the same logical name to more than 
one equivalence name. For example, you can use the same logical name to access 
different directories on different disks or to access different files in different 
directories. 


When you specify more than one equivalence name for a logical name, you create 
a search list. See the OpenVMS User’s Manual for more information on search 
lists. 


Description 


Qualifiers 


DEFINE 


The DEFINE command creates an entry in a logical name table by defining a 
logical name to stand for one or more equivalence names. An equivalence name 
can be a device name, another logical name, a file specification, or any other 
string. -~ 


To specify the logical name table where you want to enter a logical name, use the 
/PROCESS, the /GROUP, the /SYSTEM, the /JOB, or the /TABLE qualifier. If you 
enter more than one of these qualifiers, only the last one entered is accepted. If 
you do not specify a table, the default is the /TABLE=LNM$PROCESS qualifier. 


To specify the access mode of the logical name you are creating, use the /USER_ 
MODE, the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. If you 
enter more than one of these qualifiers, only the last one entered is accepted. If 
you do not specify an access mode, a supervisor-mode name is created. You can 
create a logical name in the same mode as the table in which you are placing the 
name, or in an outer mode. (User mode is the outermost mode; executive mode is 
the innermost mode.) 


You can enter more than one logical name with the same name in the same table, 
as long as each name has a different access mode. (However, if an existing logical 
name within a table has the NO_ALIAS attribute, you cannot use the same name 
to create a logical name in an outer mode in this table.) 


If you create a logical name with the same name, in the same table, and in the 
same mode as an existing name, the new logical name assignment replaces the 
existing assignment. 


You can also use the ASSIGN command to create logical names. To delete a 
logical name from a table, use the DEASSIGN command. 


Note 


Avoid assigning a logical name that matches the file name of an 
executable image in SYS$SYSTEM:. Such an assignment prohibits 
you from invoking that image. 


For additional information on how to create and use logical names, see the 
OpenVMS User’s Manual. 


/EXECUTIVE_MODE 
Requires SYSNAM (system logical name) privilege to create an executive- 
mode logical name. 


Creates an executive-mode logical name in the specified table. 


If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM 
privilege, the DEFINE command ignores the qualifier and creates a supervisor- 
mode logical name. The mode of the logical name must be the same or less 
privileged than the mode of the table in which you are placing the name. 


/GROUP 
Requires GRPNAM (group logical name) or SYSNAM (system logical 


. name) privilege to place a name in the group logical name table. 
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Places the logical name in the group logical name table. Other users who 
have the same group number in their user identification codes (UICs) can 
access the logical name. The /GROUP qualifier is synonymous with the 
/TABLE=LNM$GROUP qualifier. 


/JOB 

Places the logical name in the jobwide logical name table. All processes in the 
same job tree as the process that created the logical name can access the logical 
name. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier. 


/LOG (default) 
/NOLOG 
Displays a message when a new logical name supersedes an existing name. 


/NAME_ATTRIBUTES[=(keyword[,...])] 
Specifies attributes for a logical name. By default, no attributes are set. Possible 
keywords are as follows: 


CONFINE The logical name is not copied into a spawned subprocess. This 
qualifier is relevant only for logical names in a private table. 
The logical name inherits the CONFINE attribute from the 
logical name table where it is entered; if the logical name table 
is “confined,” then all names in the table are “confined.” 


NO_ALIAS A logical name cannot be duplicated in the specified table in 
a less privileged access mode; any previously created identical 
names in an outer (less privileged) access mode within the 
specified table are deleted. 


If you specify only one keyword, you can omit the parentheses. Only the 
attributes you specify are set. 


/PROCESS (default) 
Places the logical name in the process logical name table. The /PROCESS 
qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier. 


/SUPERVISOR_MODE (defauit) 

Creates a supervisor-mode logical name in the specified table. The mode of the 
logical name must be the same as or less privileged than the mode of the table in 
which you are placing the name. 


/SYSTEM 
Requires write (W) access or SYSNAM (system logical name) privilege to 
place a name in the system logical name table. 


Places the logical name in the system logical name table. All system users 
can access the logical name. The /SYSTEM qualifier is synonymous with the 
/TABLE=LNM$SYSTEM qualifier. 


/TABLE=name 
Requires write (W) access to the table to specify the name of a shareable 
logical name table. 


Specifies the name of the logical name table in which the logical name is to 

be entered. You can use the /TABLE qualifier to specify a user-defined logical 
name table (created with the CREATE/NAME_TABLE command); to specify the 
process, job, group, or system logical name tables; or to specify the process or 
system logical name directory tables. 


Examples 


DEFINE 


If you specify the table name using a logical name that has more than one 
translation, the logical name is placed in the first table found. For example, if 
you specify DEFINE/TABLE=LNM$FILE_DEV and LNM$FILE_DEV is equated 
to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the 
logical name is placed in LNM$PROCESS. 


The default is the /TABLE=LNM$PROCESS qualifier. 


/TRANSLATION_ATTRIBUTES[=(keyword[,...])] 
Equivalence-name qualifier. 


Specifies one or more attributes that modify an equivalence string of the logical 
name. Possible keywords are as follows: 


CONCEALED Indicates that the equivalence string is the name of a concealed 
device. When a concealed device name is defined, the system 
displays the logical name, rather than the equivalence string, in 
messages that refer to the device. 


TERMINAL Logical name translation should terminate with the current 
equivalence string; indicates that the equivalence string should 
not be translated iteratively. 


If you specify only one keyword, you can omit the parentheses. Only the 
attributes you specify are set. 


Note that different equivalence strings of a logical name can have different 
translation attributes. 


/USER_MODE 
Creates a user-mode logical name in the specified table. 


User-mode logical names created within the process logical name tables are used 
for the execution of a single image; for example, you can create a user-mode 
logical name to allow an image executing in a command procedure to redefine 
SYS$INPUT. User-mode entries are deleted from the process logical name table 
when any image executing in the process exits (that is, after a DCL command 
or user program that executes an image completes execution). Also, user-mode 
logical names are automatically deleted when invoking and exiting a command 
procedure. 


1. $ DEFINE/USER_MODE TM1 $DISK1:[ACCOUNTS.MEMOS ]WATER.TXT 


In this example, the DEFINE command defines TM1 as equivalent to 
a file specification. After the next image runs, the logical name TM1 is 
automatically deassigned. 

2. $ DEFINE MEMO $DISK1:[ACCOUNTS.MEMO] 


In this example, the DEFINE command defines the logical name MEMO as 
equivalent to the partial file specification $DISK1:[ACCOUNTS.MEMO]. 


DCLI-123 


DEFINE 


DCLI-124 


3. 


$ DEFINE PROCESS NAME LIBRA 
$ RUN WAKE 


In this example, the DEFINE command places the logical name PROCESS_ 
NAME in the process logical name table with an equivalence name of 
LIBRA. The logical name is created in supervisor mode. The program WAKE 
translates the logical name PROCESS_NAME to perform some special action 
on the process named LIBRA. 


$ DEFINE TEMP: XXX1: 


$ DEASSIGN TEMP: : 


In this example, the DEFINE command creates an equivalence name for the 
logical name TEMP: and places the name in the process logical name table. 
The colon is retained as part of the logical name. The DEASSIGN command 
deletes the logical name. Note that two colons are required on the logical 
name in the DEASSIGN command. One colon is deleted by the DEASSIGN 
command. The other colon is kept as part of the logical name. 


$ DEFINE PORTLAND PRTLND: :YYY0: [DECNET.DEMO.COM] 


In this example, the DEFINE command places the logical name 
PORTLAND in the process logical name table with an equivalence name 
of PRTLND::YYY0:[DECNET.DEMO.COM]. Subsequent references to the 
logical name PORTLAND result in the correspondence between the logical 
name PORTLAND and the node, disk, and subdirectory specified. 


$ DEFINE LOCAL "BOSTON""JOHN SMITH JKS""::" 


In this example, the DEFINE command places the logical name LOCAL 

in the process logical name table with a remote node equivalence name 

of BOSTON"JOHN_SMITH JKS"::. To satisfy conventions for local DCL 
command string processing, you must use three sets of quotation marks. The 
quotation marks ensure that access control information is enclosed in one set 
of quotation marks in the equivalence name. 


$ DEFINE MYDISK XXX0:[MYDIR], YYY0:[TESTDIR] 


In this example, the DEFINE command places the logical name MYDISK in 
the process logical name table with two equivalence names: XXX0:[MYDIR] 
and YYY0:[TESTDIR]. 


$ CREATE/NAME TABLE TABLE1 
$ DEFINE/TABLE=LNM$PROCESS DIRECTORY LNM$FILE DEV - 
$ TABLE1,LNM$PROCESS , LNM$JOB, LNMSGROUP , LNMSSYSTEM 


$ DEFINE/TABLE=TABLE1 - 
_$ /TRANSLATION_ATTRIBUTES=CONCEALED WORK DISK DBA: 


In this example, the CREATE/NAME_TABLE command creates the process 
private logical name table TABLE1. 


The first DEFINE command ensures that TABLE! is searched first in any 
logical name translation of a device or file specification (because TABLE1 is 
the first item in the equivalence string for the logical name LNM$FILE_DEV, 
which determines the default search sequence of logical name tables whenever 
a device or file specification is translated). 


DEFINE 


The second DEFINE command assigns the logical name WORK_DISK to the 
physical device DBA1 and places the name in TABLE1. The logical name 
has the concealed attribute. Therefore, the logical name WORK_DISK is 
displayed in system messages. 


$ CREATE/NAME TABLE SPECIAL 
$ DEFINE/TABLE=LNMSPROCESS DIRECTORY LNMSFILE DEV - 
$ SPECIAL, LNMSPROCESS , LNMSJOB, LNMSGROUP , LNMSSYSTEM 
§ DEFINE/TABLE=LNMS$PROCESS DIRECTORY TAB SPECIAL 
$ DEFINE/TABLE=TAB REPORT [CHELSEA]STORES 
$ SHOW LOGICAL/TABLE=SPECIAL REPORT 
“REPORT” = "[CHELSEA]STORES" (SPECIAL) 


In this example, the CREATE/NAME_TABLE command is used to create a 
new logical name table called SPECIAL. This table is defined in the process 
directory, LNM$PROCESS_DIRECTORY. 


The first DEFINE command ensures that SPECIAL is searched first in any 
logical name translation of a device or file specification (because SPECIAL is 
the first item in the equivalence string for the logical name LNM$FILE_DEV, 
which determines the default search sequence of logical name tables whenever 
a device or file specification is translated). The logical name LNM$FILE_DEV 
is placed in the process directory, LNM$PROCESS_DIRECTORY. 


With the next DEFINE command, a new logical name, TAB, is defined. TAB 
translates to the string SPECIAL, which identifies a logical name table. You 
must define TAB in the process directory because it translates iteratively to a 
logical name table. 


Next, the logical name REPORT is placed into the logical name table TAB. 
Because TAB translates to the table SPECIAL, the name REPORT is entered 
into SPECIAL table. The SHOW LOGICAL command verifies that the name 
REPORT has been entered into the table SPECIAL. 


Note that you can redefine TAB so it translates to a different table. Therefore, 
if you run different programs that use the name TAB as a table name, you 
can change the actual tables where the names are entered or referenced. 
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Format 


Parameters 


Description 
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Assigns a numeric value to a queue characteristic. The /CHARACTERISTIC 
qualifier is required. If a value has been assigned to the characteristic, you must 
delete and redefine the characteristic to alter the assignment of the existing 


. characteristic. 


Requires OPER (operator) privilege. 


Note 


You cannot define more than one characteristic name to a number. 


DEFINE/CHARACTERISTIC  characteristic-name characteristic-number 


characteristic-name 

Assigns a name to the characteristic being defined. The characteristic name can 
be the name of an existing characteristic or a string of 1 to 31 characters that 
defines a new characteristic. The character string can include any uppercase and 
lowercase letters, digits, the dollar sign ($), and the underscore (_), and must 
include at least one alphabetic character. Only one characteristic name can be 
defined to each number. 


characteristic-number 
Assigns a number in the range 0 to 127 to the characteristic being defined. 


The system manager or operator uses the DEFINE/CHARACTERISTIC command 


to assign a name and number to a particular characteristic for queues in the 


system. Characteristics can refer to any attribute of a print or batch job that is 
meaningful for your environment. The name and number of a characteristic are 
arbitrary, but they must be unique for that characteristic. 


Note 


Prior to OpenVMS Version 6.0, the DEFINE/CHARACTERISTIC 
command allowed you to define more than one characteristic name to 
a number, although this capability was unsupported. 


The DEFINE/CHARACTERISTIC command no longer allows you to define 
more than one characteristic name to a number. However, if your queue 
configuration requires you to have more than one characteristic name for 
a single number, you can define logical names to achieve the same result. 
For example, you might enter the following commands: 


$ DEFINE/CHARACTERISTIC SECOND FLOOR 2 
$ DEFINE/SYSTEM/EXECUTIVE MODE SALES FLOOR SECOND FLOOR 
$ DEFINE/SYSTEM/EXECUTIVE MODE SALES DEPT SECOND FLOOR 


In this example, the characteristic name SECOND_FLOOR is assigned 
to the characteristic number 2. The logical names SALES_FLOOR 
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and SALES_DEPT are then defined as equivalent to the characteristic 
name SECOND_FLOOR. As a result, the logical names SALES_FLOOR 
and SALES_DEPT are each equivalent to the characteristic name 
SECOND_FLOOR and the characteristic number 2. These logical 
names can be specified as the characteristic-name value for any 
/CHARACTERISTIC=characteristic-name qualifier. 


In a VMScluster environment, you must define the logical names on every 
node that requires them. 


After characteristics have been defined, they can be associated with print or batch 
jobs and execution queues. For information on specifying characteristics with 
jobs, see the description of the (CHARACTERISTICS qualifier of the PRINT and 
SUBMIT commands. 


To find out what characteristics are currently defined for the system, use the 
SHOW QUEUE/CHARACTERISTICS command. To find out which characteristics 
have been specified for a particular queue, use the SHOW QUEUE/FULL 
command. For information on associating characteristics with queues, see the 
descriptions of the (CHARACTERISTICS qualifier of the INITIALIZE/QUEUE, 
SET QUEUE, and START/QUEUE commands. 


The DELETE/CHARACTERISTIC command deletes a previously defined 
characteristic. 


For more information on specifying queue characteristics, see the OpenVMS 
System Manager’s Manual. 


$ DEFINE/CHARACTERISTIC REDINK 3 


The DEFINE/CHARACTERISTIC command in this example defines the 
characteristic REDINK with the number 3. When a user enters the command 
PRINT/CHARACTERISTICS=REDINK (or PRINT /CHARACTERISTICS=3), the 
job is printed only if the printer queue has been established with the REDINK or 
3 characteristic. 
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Assigns a numeric value and attributes to a print form name. The /FORM 
qualifier is required. To modify a form’s name or number, you must delete and 
redefine the form. Values for any DEFINE/FORM qualifier can be modified by 
re-entering the DEFINE/FORM command with different values, as long as the 
form name and number remain the same. 


Requires OPER (operator) privilege. 
DEFINE/FORM form-name form-number 


form-name 

Assigns a name to the form being defined. The form name can be the name of an 
existing form type or a string of 1 to 31 characters that defines a new form type. 
The character string can include any uppercase and lowercase letters, digits, the 
dollar sign ($), and the underscore (_), and must include at least one alphabetic 
character. 


form-number 

Assigns a number in the range 0 to 9999 to the form being defined. The 
DEFAULT form, which is defined automatically when the system is bootstrapped, 
is assigned number zero. 


The system manager or operator uses the DEFINE/FORM command to assign a 
name and number to a type of paper stock and printing area for use with printer 
or terminal queues. When a new queue file is created, the system defines a form 
named DEFAULT with a form number of zero and all the default attributes. 


Some DEFINE/FORM qualifiers specify the area for printing. The LEFT and 
RIGHT options of the /MARGIN qualifier and the /WIDTH qualifier determine 
the number of characters per line. Using the RIGHT option of the MARGIN 
qualifier and the /WIDTH qualifier, you can affect the point at which lines of text 
wrap. (You cannot use the LEFT and RIGHT options of the /MARGIN qualifier 
and the /WIDTH qualifier for filling or formatting the text, however.) 


You also can use the DEFINE/FORM command to specify different types of paper 
stock. The /DESCRIPTION qualifier enables you to describe more fully the form 
name. 


After forms have been defined, they can be associated with print jobs and 
output execution queues. For information on specifying forms with jobs, see the 
description of the PRINT/FORM command. 


To find out what forms have been defined for the system, use the SHOW QUEUE 
/FORM command. To find out which form is mounted currently on a particular 
queue and which form is specified as that queue’s default form, use the SHOW 
QUEUE/FULL command. For information on associating forms with queues, 

see the descriptions of the /DEFAULT and /FORM_MOUNTED qualifiers of the 
INITIALIZE/QUEUE, SET QUEUE, and START/QUEUE commands. 
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For more information on how to use forms to control print jobs, see the OpenVMS 
System Manager’s Manual. 


/DESCRIPTION=string 
A string of up to 255 characters used to provide operator information about the 
form. The default string is the specified form name. 


The string can be used to define the form type more specifically. For example, 
if you have form names such as LETTER1, LETTER2, and LETTERS, the 
/DESCRIPTION qualifier could be used to let the users and operators know that 
LETTER! refers to the standard corporate letterhead paper (8.5 inches x 11 
inches), LETTER2 refers to the smaller corporate letterhead paper (6 inches x 9 
inches), and LETTERS refers to the president’s personalized letterhead paper. 


Enclose strings containing lowercase letters, blanks, or other nonalphanumeric 
characters (including spaces) in quotation marks (“ ”). 


/LENGTH=n 

Specifies the physical length of a form page in lines. The default page length is 
66 lines, which assumes a standard page length of 11 inches with 6 lines of print 
per inch. The parameter n must be a positive integer greater than zero and not 
more than 255. 


The print symbiont sets the page length of the device equal to the form length. 
This enables the driver to compute the number of line feeds for devices lacking 
mechanical form feed. 


/MARGIN=(optionf....]) 
Specifies one or more of the four margin options: BOTTOM, LEFT, RIGHT, and 
TOP. 


BOTTOM=n Specifies the number of blank lines between the end of the print 
image area and the end of the physical page; the value of n 
must be between 0 and the value of the (LENGTH qualifier. 
The default value is 6, which generally means a 1-inch bottom 
margin. 

LEFT=n Specifies the number of blank columns between the leftmost 
printing position and the print image area; the value of n 
must be between 0 and the value of the /WIDTH qualifier. The 
default is 0, which means that the print image area starts as far 
to the left of the paper as the printer can go. 


RIGHT=n Specifies the number of blank columns between the /WIDTH 
qualifier and the image area; the value of n must be between 
0 and the value of the /WIDTH qualifier. When determining 
the value of the RIGHT option, start at the (WIDTH value and 
count to the left. The default value is 0, which means that the 
print image extends as far to the right as the (WIDTH value. 


TOP=n Specifies the number of blank lines between the top of the 
physical page and the top of the print image; the value of n 
must be between 0 and the value of the /LENGTH qualifier. 
The default value is 0, which generally means that there is no 
top margin. 
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/PAGE_SETUP=(module....]) 

/NOPAGE_SETUP (default) 

Specifies one or more modules that set up the device at the start of each page. 
The modules are located in the device control library. While the form is mounted, 
the system extracts the specified module and copies it to the printer before each 
page is printed. 


/SETUP=(modulef,...]) 

Specifies one or more modules that set up the device at the start of each file. The 
modules are located in the device control library. While the form is mounted, the 
system extracts the specified module and copies it to the printer before each file 
is printed. 


For more information on device control modules, see the chapter on Batch and 
Print Operations in the OpenVMS System Manager’s Manual. 


/SHEET_FEED 

/NOSHEET_FEED (default) 

Specifies that print jobs pause at the end of every physical page so that a new 
sheet of paper can be inserted. 


/STOCK=string 

Specifies the type of paper stock to be associated with the form. The string 
parameter can be a string of 1 to 31 characters, including the dollar sign, 
underscore, and all alphanumeric characters. If you specify the /STOCK qualifier 
you must specify the name of the stock to be associated with the form. If you do 
not specify the /STOCK qualifier, the name of the stock will be the same as the 


- name of the form. 


You can create any string that you want. However, when you are creating forms 
with the same stock, be sure that the /STOCK string is identical in all the 
DEFINE/FORM commands that refer to the same type of paper. 


If you are defining a number of forms to provide different formatting options, 
specify the same stock type for each form. Jobs that request any of these forms 
will print on the same queue. If you want to modify the stock string associated 
with a form, you can do this only if the form is not referenced by any job or queue. 


/TRUNCATE (default) 

/INOTRUNCATE 

Discards any characters that exceed the current line length (specified by the 
/WIDTH and /MARGIN=RIGHT qualifiers). The /TRUNCATE qualifier is 
incompatible with the /WRAP qualifier. If you specify both the /NOTRUNCATE 
and /NOWRAP qualifiers, the printer prints as many characters on a line as 
possible. This combination of qualifiers is useful for some types of graphics 
output. 


/WIDTH=n 

Specifies the physical width of the paper in terms of columns or character 
positions. The parameter n must be an integer from 0 to 65,535; the default 
value is 132. 


Any lines exceeding this value wrap if the /WRAP qualifier is in effect or are 
truncated if the /TRUNCATE qualifier is in effect. (If both the /NOTRUNCATE 
and /NOWRAP qualifiers are in effect, lines print as far as possible.) 


The /MARGIN=RIGHT qualifier overrides the /WIDTH qualifier when 
determining when to wrap lines of text. 
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/WRAP 

/NOWRAP (default) 

Causes lines that exceed the current line length (specified by the /WIDTH and 
/MARGIN=RIGHT qualifiers) to wrap onto the next line. The /WRAP qualifier is 
incompatible with the /TRUNCATE qualifier. If you specify both the /NOWRAP 
and /NOTRUNCATE qualifiers, the printer prints as many characters on a line 
as possible. This combination of qualifiers is useful for some types of graphics 
output. 


$ DEFINE/FORM /MARGIN=(TOP=6,LEFT=10) CENTER 3 


The DEFINE/FORM command in this example defines the form CENTER to have 
a top margin of 6 and a left margin of 10. The defaults remain in effect for both 
bottom margin (6) and right margin (0). The form is assigned the number 38. 
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Associates an equivalence string and a set of attributes with a key on the 
terminal keyboard. 


DEFINE/KEY key-name equivalence-string 


key-name 

Specifies the name of the key that you are defining. All definable keys on VT52 
terminals are located on the numeric keypad. On VT100-series terminals, you 

can define the left and right arrow keys as well as all the keys on the numeric 

keypad. On terminals with LK201 keyboards, the following three types of keys 
can be defined: | 


e Keys on the numeric keypad 
e Keys on the editing keypad (except the up and down arrow keys) 


e Keys on the function key row across the top of the keyboard (except keys F1 
to F5) 


The following table lists the key names in column one. The remaining three 
columns indicate the key designations on the keyboards of the three different 
types of terminals that allow key definitions. 


Key Name LK201 © VT100-Series VT52 
PF1 PF1 PF1 [blue] 
PF2 PF2 PF2 [red] 
PF3 PF3 PF3 [gray] 
PF4 PF4 PF4 -- 

KPO, KP1, ..., KP9 0.1) 2-9 0,1,...,9 0, 1,...,9 
Period 

Comma , : n/a 
Minus - - n/a 
Enter Enter ENTER ENTER 
Left — — — 
Right _ — — 

Find (E1) Find — — 
Insert Here (E2) Insert Here — — 
Remove (E3) Remove — — 
Select (E4) Select — — 

Prev Screen (E5) Prev Screen — — 
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Key Name LK201 VT100-Series VT52 
Next Screen (E6) Next Screen — — 
Help Help — — 
Do Do — — 
F6, F7, ..., F20 F6, F7, ..., F20 — — 


Some definable keys are enabled for definition all the time. Others, including KPO 
to KP9, Period, Comma, and Minus, must be enabled for definition purposes. You 
must enter either the SET TERMINAL/APPLICATION or the SET TERMINAL 
/NONUMERIC command before using these keys. 


On LK201 keyboards, you cannot define the up and down arrow keys or function 
keys F1 to F5. The left and right arrow keys and the F6 to F14 keys are reserved 
for command line editing. You must enter the SET TERMINAL/NOLINE_ 
EDITING command before defining these keys. You can also press Ctrl/V to 
enable keys F7 to F14. Note that Ctrl/V will not enable the F6 key. 


equivalence-string 
Specifies the character string to be processed when you press the key. Enclose the 
string in quotation marks (“”) to preserve spaces and lowercase characters. 


The DEFINE/KEY command enables you to assign definitions to the peripheral 
keys on certain terminals. The terminals include VT52s, the VT100 series, and 
terminals with LK201 keyboards. 


To define keys on the numeric keypads of these terminals, you must first enter the 
SET TERMINAL/APPLICATION or SET TERMINAL/NONUMERIC command. 
When your terminal has this setting, the system interprets the keystrokes from 
keypad keys differently. For example, with SET TERMINAL/NONUMERIC in 
effect, pressing the 1 key on the keypad does not send the character “1” to the 
system. 


The equivalence string definition can contain different types of information. 
Definitions often consist of DCL commands. For example, you can assign SHOW ~ 
TIME to the zero key. When you press 0, the system displays the current date 
and time. Other definitions can consist of text strings to be appended to command 
lines. When you define a key to insert a text string, use the /NOTERMINATE 
qualifier so that you can continue typing more data after the string has been 
inserted. 


In most instances you will want to use the echo feature. The default setting is 
/ECHO. With /ECHO set, the key definition is displayed on the screen each time 
you press the key. 


You can use the /STATE qualifier to increase the number of key definitions 
available on your terminal. The same key can be assigned any number of 
definitions, as long as each definition is associated with a different state. State 
names can contain any alphanumeric characters, dollar signs, and underscores. 
Be sure to create a state name that is easy to remember and type and, if possible, 
one that might remind you of the types of definitions you created for that state. 
For example, you can create a state called SETSHOW. The key definitions for this 
state might all refer to various DCL SET and SHOW commands. If you are used 
to the EDT Editor, you might define a state as GOLD. Then, using the IF_STATE 
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qualifier, you can assign different definitions to keys used in combination with a 
key defined as GOLD. 


The SET KEY command changes the keypad state. Use the SHOW KEY 
command to display key definitions and states. 


/ECHO (default) 

/NOECHO 

Displays the equivalence string on your screen after the key has been pressed. 
You cannot use the /NOECHO qualifier with the /NOTERMINATE qualifier. 


/ERASE 

/NOERASE (default) 

Determines whether the current line is erased before the key translation is 
inserted. 


AF_STATE=(state-name.,...) 

/NOIF_STATE 

Specifies a list of one or more states, one of which must be in effect for the key 
definition to work. The /NOIF_STATE qualifier has the same meaning as /IF_ 
STATE=current_state. The state name is an alphanumeric string. States are 
established with the /SET_STATE qualifier or the SET KEY command. If you 
specify only one state name, you can omit the parentheses. By including several 
state names, you can define a key to have the same function in all the specified 
states. 


/LOCK_STATE 

/NOLOCK_STATE (default) 

Specifies that the state set by the /SET_STATE qualifier remain in effect until 
explicitly changed. (By default, the /SET_STATE qualifier is in effect only for 
the next definable key you press or the next read-terminating character that you 
type.) This qualifier can be specified only with the /SET_STATE qualifier. 


/LOG (default) 

INOLOG 

Displays a message indicating that the key definition has been successfully 
created. 


/SET_STATE=state-name 

/NOSET_STATE (default) 

Causes the specified state-name to be set when the key is pressed. (By default, 
the current locked state is reset when the key is pressed.) If you have not 
included this qualifier with a key definition, you can use the SET KEY command 
to change the current state. The state name can be any alphanumeric string; 
specify the state as a character string enclosed in quotation marks. 


/TERMINATE 

/NOTERMINATE (default) 

Specifies whether the current equivalence string is to be processed immediately 
when the key is pressed (equivalent to entering the string and pressing the 
Return key). By default, you can press other keys before the definition is 
processed. This allows you to create key definitions that insert text into command 
lines, after prompts, or into other text that you are entering. 


Examples 


1. 


DEFINE/KEY 


$ DEFINE/KEY PF3 "SHOW TIME" /TERMINATE 
$DCL-I-DEFKEY, DEFAULT key PF3 has been defined 


$ [PFS] 
$ SHOW TIME 
14-DEC-1994 14:43:59 


In this example, the DEFINE/KEY command defines the PF3 key on the 
keypad to perform the SHOW TIME command. DEFAULT refers to the 
default state. 


$ DEFINE/KEY PF1 "SHOW " /SET STATE=GOLD/NOTERMINATE/ECHO 
$DCL-I-DEFKEY, DEFAULT key PF1 has been defined 

$ DEFINE/KEY PFl " DEFAULT" /TERMINATE/IF STATE=GOLD/ECHO 
$DCL-I-DEFKEY, GOLD key PF1 has been defined 


$ 

$ [Pri 

$ SHOW DEFAULT 
DISK1:[JOHN. TEST] 


In this example, the first DEFINE/KEY command defines the PF1 key to 

be the string SHOW. The state is set to GOLD for the subsequent key. The 
/NOTERMINATE qualifier instructs the system not to process the string 
when the key is pressed. The second DEFINE/KEY command defines the use 
of the PF1 key when the keypad is in the GOLD state. When the keypad is in 
the GOLD state, pressing PF1 causes the current read to be terminated. 


If you press the PF1 key twice, the system displays and processes the SHOW 
DEFAULT command. 


The word DEFAULT in the second line of the example indicates that the PF1 
key has been defined in the default state. Note the space before the word 

DEFAULT in the second DEFINE/KEY command. If the space is omitted, the 
system fails to recognize DEFAULT as the keyword for the SHOW command. 


$ SET KEY/STATE=ONE 

tDCL-I-SETKEY, keypad state has been set to ONE 
$ DEFINE/KEY PF1l "ONE" 

$DCL-I-DEFKEY, ONE key PF1 has been defined 

$ DEFINE/KEY/IF STATE=ONE PF1 "ONE" 
*DCL-I-DEFKEY, ONE key PF1 has been defined 


This example shows two ways to define the PF1 key to be “ONE?” for state 
ONE. 


The second DEFINE/KEY command shows the preferred method for defining 
keys. This method eliminates the possibility of error by specifying the state 
in the same command as the key definition. 
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Deletes one or more files from a mass storage disk volume. 


Requires delete (D) access to the file and write (W) access to the parent 
directory. If the target file is itself a directory, the directory must be 
empty. 


DELETE filespecf,...] 


filespecf,...] 

Specifies the names of one or more files to be deleted from a mass storage disk 
volume. The first file specification must contain an explicit or default directory 
specification plus an explicit file name, file type, and version number. Subsequent 
file specifications need contain only a version number; the defaults will come from 
the preceding specification. The asterisk (*) and the percent sign (% ) wildcard 
characters can be used in any of the file specification fields. 


If you omit the directory specification or device name, the current default device 
and directory are assumed. 


If the file specification contains a null version number (a semicolon (;) followed 
by no file version number), a version number of 0, or one or more spaces in the 
version number, the latest version of the file is deleted. 


To delete more than one file, separate the file specifications with either commas 
(,) or plus signs (+). 


/BACKUP 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /BACKUP qualifier selects files according to the dates of their most recent 
backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/BEFORE[=time] 

Selects only those files dated prior to the specified time. You can specify time 
as absolute time, as a combination of absolute and delta times, or as one of 

the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


/BY_OWNER[=uic] 
Selects only those files whose owner user identification code (UIC) matches the 
specified owner UIC. The default UIC is that of the current process. 
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Specify the UIC by using standard UIC format as described in the OpenVMS 
Guide to System Security. 


/CONFIRM 

/NOCONFIRM (default) 

Controls whether a request is issued before each delete operation to confirm that 
the operation should be performed on that file. The following responses are valid: 


YES NO QUIT - 
TRUE FALSE Ctrl/Z 
1 0 ALL 


You can use any combination of uppercase and lowercase letters for word 
responses. Word responses can be abbreviated to one or more letters (for example, 
T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative 
answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, 

and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that 
you want to stop processing the command at that point. When you respond by 
entering ALL, the command continues to process, but no further prompts are 
given. If you type a response other than one of those in the list, DCL issues an 
error message and redisplays the prompt. 


/CREATED (default) 

Modifies the time value seated with the /BEFORE or the /SINCE qualifier. The 
/CREATED qualifier selects files based on their dates of creation. This qualifier is 
incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which 
also allow you to select files according to time attributes. If you specify none of 
these four time qualifiers, the default is the /CREATED qualifier. 


/ERASE 

/NOERASE (default) 

When you delete a file, the area in which the file was stored is returned to the 
system for future use. The data that was stored in that location still exists in the 
system until new data is written over it. When you specify the /ERASE qualifier, 
the storage location is overwritten with a system specified pattern so that the 
data no longer exists. 


/EXCLUDE=(filespec[.,...]) 

Excludes the specified files from the delete operation. You can include a directory 
but not a device in the file specification. The asterisk (*) and the percent sign 
(%) wildcard characters are allowed in the file specification. However, you cannot 
use relative version numbers to exclude a specific version. If you specify only one 
‘file, you can omit the parentheses. 


/EXPIRED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /EXPIRED qualifier selects files according to their expiration dates. (The 
expiration date is set with the SET FILE/EXPIRATION_DATE command.) 
The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 
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/LOG 

/NOLOG (default) 

Controls whether the DELETE command displays the file specification of each file 
after its deletion. 


/MODIFIED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /MODIFIED qualifier selects files according to the dates on which they were 
last modified. This qualifier is incompatible with the /BACKUP, /CREATED, 
and /EXPIRED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time modifiers, the default is the 
/CREATED qualifier. 


/SINCE[=time] 

Selects only those files dated after the specified time. You can specify time 

as absolute time, as a combination of absolute and delta times, or as one of 
the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


1. $ DELETE COMMON.SUM;2 


The DELETE command deletes the file COMMON.SUM;2 from the current 
default disk and directory. 


2. $ DELETE *.OLD;* 


The DELETE command deletes all versions of files with file type .OLD from 
the default disk directory. 


8. $ DELETE ALPHA.TXT;*, BETA;*, GAMMA;* 


The DELETE command deletes all versions of the files ALPHA.TXT, 
BETA.TXT, and GAMMA.TXT. The command uses the file type of the first 
input file as a temporary default. Note, however, that some form of version 
number (here specified as the asterisk (*) wildcards) must be included in 
each file specification. 


4. $§ DELETE /BEFORE=15-APR/LOG *.DAT;* 
$DELETE-I-FILDEL, DISK2:{MALCOLM]ASSIGN.DAT;1 deleted (5 block) 
$DELETE-I-FILDEL, DISK2:{MALCOLM]BATCHAVE.DAT;3 deleted (4 blocks) 
$DELETE-I-FILDEL, DISK2:[MALCOLM]BATCHAVE.DAT;2 deleted (4 blocks) 
*DELETE-I-FILDEL, DISK2:[MALCOLM]BATCHAVE.DAT;1 deleted (4 blocks) 
*DELETE-I-FILDEL, DISK2:[MALCOLM]CANCEL.DAT;1 deleted (2 blocks) 
$DELETE-I-FILDEL, DISK2:[MALCOLM]DEFINE.DAT;1 deleted (3 blocks) 
$DELETE-I-FILDEL, DISK2:{MALCOLMJEXIT.DAT;1 deleted (1 block) 
tDELETE-I-TOTAL, 7 files deleted (23 blocks) 


The DELETE command deletes all versions of all files with file type .DAT 
that were either created or updated before April 15 of this year. The /LOG 
qualifier not only displays the name of each file deleted, but also the total 
number of files deleted. 
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$ DELETE A.B; 
The DELETE command deletes the file A.B with the highest version number. 


$ DELETE/CONFIRM/SINCE=TODAY [MALCOLM.TESTFILES ]*.OBJ;* 
DISKO: [MALCOLM. TESTFILES ]AVERAG.OBJ;1, delete? [N]:¥ 
DISKO: [MALCOLM. TESTFILES ]SCANLINE.OBJ;4, delete? [N]:N 
DISKO: [MALCOLM. TESTFILES ]SCANLINE.OBJ;3, delete? [N]:N 
DISKO: [MALCOLM. TESTFILES ]SCANLINE.OBJ;2, delete? [N]:N 
DISKO: [MALCOLM. TESTFILES ]WEATHER.OBJ;3, delete? [N]:Y 


The DELETE command examines all versions of files with file type OBJ 

in the subdirectory [MALCOLM.TESTFILES], and locates those that were 
created or modified today. Before deleting each file, it requests confirmation 
that the file should be deleted. The default response—N—is given in brackets. 


$ DIRECTORY [{.SUBTEST] 

$DIRECT-W-NOFILES, no files found 

$ SET PROTECTION SUBTEST.DIR/PROTECTION=OWNER :D 
$ DELETE SUBTEST.DIR;1 


Before the directory file SUBTEST.DIR is deleted, the DIRECTORY command 
is used to verify that there are no files cataloged in the directory. The SET 
PROTECTION command redefines the protection for the directory file so that 
it can be deleted; then the DELETE command deletes it. 


$ DELETE DALLAS"THOMAS SECRET": :DISK0:[000,000]DECODE.LIS;1 


This DELETE command deletes the file DECODE.LIS;1 from the directory 
[000,000] on device DISKO at remote node DALLAS. The user name and 
password follow the remote node name. 


$ DELETE NODE12::"DISK1:DEAL.BIG" 
$ DELETE NODE12::DISK1:DEAL.BIG; 


Hither of these DELETE commands can be used to delete the file DEAL.BIG 
on device ZZZ1 at remote node NODE12. Note that the DELETE command 
requires an explicit version number in a file specification, but the file to be 
deleted is on a remote node whose file syntax does not recognize version 
numbers. (NODE12 is an RT-11 node.) Therefore, the file specification must 
either be enclosed in quotation marks (“”) or entered with a null version 
number (that is, a trailing semicolon [;)]). 
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DELETE/CHARACTERISTIC 


Format 


Parameter 


Description 


Qualifier 


Example 
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Deletes the definition of a queue characteristic previously established with the 
DEFINE/CHARACTERISTIC command. The /CHARACTERISTIC qualifier is 
required. 


Requires OPER (operator) privilege. 
DELETE/CHARACTERISTIC  characteristic-name 


characteristic-name 
Specifies the name of the characteristic to be deleted. 


The DELETE/CHARACTERISTIC command deletes a characteristic from the 
system characteristic table. 


To modify a characteristic’s name or number, you must delete and redefine the 
characteristic. 


/LOG 

/NOLOG (default) 

Controls whether the DELETE/CHARACTERISTIC command displays the name 
of each characteristic after its deletion. 


$ DEFINE/CHARACTERISTIC BLUE 7 


$ DELETE/CHARACTERISTIC BLUE 
$ DEFINE/CHARACTERISTIC BLUE_INK 7 


The DEFINE/CHARACTERISTIC command in this example establishes the 
characteristic BLUE, with number 7, to mean blue ink ribbons for printers. To 
change the name of the characteristic, enter the DELETE/CHARACTERISTIC 
command. Then enter another DEFINE/CHARACTERISTIC command to rename 
the characteristic to BLUE_INK, using the characteristic number 7. 


DELETE/ENTRY 


DELETE/ENTRY 


Format 


Parameters 


Description 


Qualifier 


Deletes one or more print or batch jobs. The jobs can be in progress or waiting in 
the queue. The /ENTRY qualifier is required. 


Requires manage (M) access to the queue, or delete (D) access to the 
specified jobs. . 


DELETE/ENTRY=(entry-number{,...]) [queue-name[:]] 


entry-number{,...] 

Specifies the entry number (or a list of entry numbers) of jobs to be deleted. If 
you specify only one entry number, you can omit the parentheses. If you do not 
specify a queue name, you can delete entries from multiple queues. 


The system assigns a unique entry number to each queued print or batch job in 
the system. By default, the PRINT and SUBMIT commands display the entry 
number when they successfully queue a job for processing. These commands also 
create or update the local symbol $ENTRY to reflect the entry number of the 
most recently queued job. To find a job’s entry number, enter the SHOW ENTRY 
or SHOW QUEUE command. 


queue-name[:] 

Specifies the name of the queue where the jobs are located. The queue name can 
refer either to the queue to which the job was submitted or to the queue where 
the job is executing. The queue-name parameter is optional syntax. However, 
when you specify a queue name, the operating system uses it to verify an entry in 
the specific queue before deleting the entry. 


The DELETE/ENTRY command deletes one or more jobs from a queue. If you 
specify a queue name and more than one entry number with a DELETE/ENTRY 
command, all the jobs must be located in the same queue. 


You can delete jobs that are currently executing, as well as jobs that are in other 
states. For example, DELETE/ENTRY can delete a job that is currently in a 
holding or a pending state. 


/LOG 

/NOLOG (default) 

Controls whether the DELETE/ENTRY command displays the entry number of 
each batch or print job that it deletes. 
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1. 


$ PRINT/HOLD ALPHA.TXT 
Job ALPHA (queue SYS$PRINT, entry 110) holding 


$ DELETE/ENTRY=110 SYS$PRINT 


The PRINT command in this example queues a copy of the file ALPHA.TXT 
in a HOLD status, to defer its printing until a SET ENTRY/RELEASE 
command is entered. The system displays the job name, the entry number, 
the name of the queue in which the job was entered, and the status. Later, 
the DELETE/ENTRY command Fe that the entry be deleted from the 
queue SYS$PRINT. 


$ SUBMIT/AFTER=18:00 WEATHER 

Job WEATHER (queue SYSS$BATCH, entry 203) holding until 14-DEC-1994 
18:00 

$ SUBMIT/HOLD/PARAMETERS=SCANLINE DOFOR 

Job DOFOR (queue SYSS$BATCH, entry 210) holding 


$ DELETE/ENTRY=(203,210)/LOG 
$DELETE-W~SEARCHFAIL, error searching for 203 
-JBC-E-NOSUCHENT, no such entry 
$DELETE-I-DELETED, entry 210 aborting or deleted 


The SUBMIT commands in this example queue the command procedures 
WEATHER.COM and DOFOR.COM for processing as batch jobs. 
WEATHER.COM is queued for execution after 6:00 PM. DOFOR.COM is 
queued in a HOLD status and cannot execute until you enter a SET ENTRY 
/RELEASE command. Later, the DELETE/ENTRY/LOG command requests 
that the system delete both these entries from the queue and display a 
message indicating that the entries have been deleted. 


The job WEATHER (entry 203) has completed by the time the DELETE 
/ENTRY/LOG command is entered. Thus, entry 203 no longer exists. Note 
that a message indicates that there is no entry 203 in the queue. The job 
DOFOR (entry 210) is in a HOLD status when the DELETE/ENTRY/LOG 
command is entered. Thus, the system deletes entry 210 from the queue and 
displays a message to that effect. 


$ PRINT CHAPTERS .MEM 
Job CHAPTER8 (queue SYSSPRINT, entry 25) pending on queue SYSSPRINT 


$ SHOW QUEUE SYS$PRINT 
Printer queue SYS$PRINT, on PARROT::PARROTSLPA0, mounted form DEFAULT 


Entry Jobname Username Status 
24 CHAPTER7 SMITH Pending 
25 . CHAPTER8 SMITH Pending 


$ DELETE/ENTRY=25 


DELETE/ENTRY 


The PRINT command in this example submits the file CHAPTER8.MEM to 
the printer queue SYS$PRINT. Later, user Smith needs to edit the file again 
before printing it. Using the SHOW QUEUE command, Smith verifies that 
the job is still pending and that the entry number for the job is 25. Smith 
then enters the DELETE/ENTRY command to delete the job from the 

queue. 
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DELETE/FORM 


DELETE/FORM 


Format 


Parameter 


Description 


Qualifier 


Examples 


Deletes a form (for printer or terminal queues) previously established with the 
DEFINE/FORM command. The /FORM qualifier is required. 


Requires OPER (operator) privilege. 


DELETE/FORM form-name 


form-name | 
Specifies the name of the form to be deleted. 


The DELETE/FORM command deletes a form definition from the system forms 
table. When you delete a form, there can be no outstanding references to the form 
either in queues that have been mounted with the form or by jobs requesting 
that form. To locate all references to the form, use the SHOW QUEUE/FULL 
command. | 


To modify a form’s name or number, you must delete and redefine the form. 
Values for any DEFINE/FORM qualifier can be modified by re-entering the 
DEFINE/FORM command with different values, as long as the form name and 
number remain the same. 


/LOG 

/NOLOG (default) 

Controls whether the DELETE/FORM command displays the name of each form | 
after its deletion. 


1. $ DELETE/FORM CENTER 


The DELETE/FORM command in this example deletes the form named CENTER. 


2. $ DEFINE/FORM - 
_$ /DESCRIPTION="letter size continuous form paper" CFLET 7 


$ DELETE/FORM CFLET 
$ DEFINE/FORM - 
_$ /DESCRIPTION="letter size continuous form paper" LETTER CONT 7 
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The DEFINE/FORM command in this example establishes the form CFLET with 
number 7 to mean continuous-form paper 8.5 inches by 11 inches. To change the 


name of the form, delete the form named CFLET and define a new one named 
LETTER_CONT. 


DELETE/INTRUSION_RECORD 


DELETE/INTRUSION_RECORD 


Format 


Parameter 


Description 


Examples 


Removes an entry from the break-in database. 
Requires CMKRNL (change mode to kernel) and SECURITY privileges. 


DELETE/INTRUSION_RECORD source 


source 

Specifies the name of the device or the remote system where the user is 
attempting to log in. The source name can be presented in the syntax of another 
operating system domain, for example, one that is case sensitive or conflicts 
with DCL syntax rules. In such cases, you must enclose the source parameter in 
quotation marks. 


Use the DELETE/INTRUSION_RECORD command to remove an entry from 
the break-in database. For example, if the user Hammer repeatedly attempted 
to log in to terminal TTA24 with an expired password, the SHOW INTRUSION 
command would display the following entry: 


Intrusion Type Count Expiration Source 


TERM USER INTRUDER 9 10:29:39.16 TTA24:HAMMER 


The terminal is locked out of the system because the login failure limit has 
been reached. When Hammer approaches you and you identify the problem as 
an expired password, you can then use the DELETE/INTRUSION command to 
remove the record from the break-in database. 


1. 3 DELETE/ INTRUSION RECORD TTC2: 


In this example, the DELETE/INTRUSION_RECORD command removes all 
intrusion records generated by break-in attempts on TTC2. No user name is 
specified because none of the login failures occurred for valid users. 


2. § DELETE/INTRUSION RECORD "AV34C2/LC-2-10":FORGETFUL 


In this example, the source of the break-in is a local terminal that is 
connected to a terminal server. To delete the record from the break-in 
database, you must enclose the terminal port name within quotation marks 
so that the operating system interprets the slash as a foreign character and 
not as a qualifier. 


3. $ DELETE/INTRUSION RECORD NODE1: :HAMMER 


This command removes all intrusion entries generated from node NODE1 for 
user HAMMER. 
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DELETE/KEY 


Format 


Parameter 


Qualifiers - 


Examples 
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Deletes key definitions that have been established by the DEFINE/KEY 
command. The /KEY qualifier is required. 


DELETE/KEY [key-name] 


key-name 
Specifies the name of the key to be deleted. This parameter is incompatible with 
the /ALL qualifier. 


/ALL 

Deletes all key definitions in the specified state; the default is the current state. 
If you use the /ALL qualifier, do not specify a key name. Use the /STATE qualifier 
to specify one or more states. 


/LOG (default) 

INOLOG 

Controls whether messages are displayed indicating that the specified key 
definitions have been deleted. 


/STATE=(state-namef....]) 

/NOSTATE (default) 

Specifies the name of the state for which the specified key definition is to be 
deleted. The default state is the current state. If you specify only one state name, 
you can omit the parentheses. State names can be any alphanumeric string. 


1. $ DELETE/KEY/ALL 
$DCL-I-DELKEY, DEFAULT key PF1 has been deleted 
tDCL-I-DELKEY, DEFAULT key PF2 has been deleted 
*DCL-I-DELKEY, DEFAULT key PF3 has been deleted 
$DCL-I-DELKEY, DEFAULT key PF4 has been deleted 
$ 


In this example, the user has defined keys PF1 to PF4 in the default state. 
The DELETE/KEY command deletes all key definitions in the current state, 
which is the default state. 


2. $ DEFINE/KEY PF3 "SHOW TIME" /TERMINATE 
$DCL-I-DEFKEY, DEFAULT key PF3 has been defined 
$ [PFS] 
$ SHOW TIME 

14-DEC-1994 14:43:59 


$ DELETE/KEY PF3 

$DCL-I-DELKEY, DEFAULT key PF3 has been deleted 
$ 7 

$ 


DELETE/KEY 


In this example, the DEFINE/KEY command defines the PF8 key on the 
keypad as SHOW TIME. To delete the definition for the PF3 key, use the 
DELETE/KEY command. When the user presses PF3, only the system 
prompt is displayed. 
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DELETE/QUEUE 


DELETE/QUEUE 


Format 


Parameter 


Description 


Qualifier 
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Deletes a print or batch queue created by the INITIALIZE/QUEUE command, 
and deletes all the jobs in the queue. The /QUEUE qualifier is required. 


Requires manage (M) access to the queue. 


DELETE/QUEUE queue-name[:] 


queue-name[:] 
Specifies the name of the queue to be deleted. 


To delete a queue, use the following procedure: 


1. Stop the specified queue by using the STOP/QUEUE/NEXT command. 


The STOP/QUEUE/NEXT command stops the specified queue after all 
executing jobs have completed processing. Wait for any executing jobs to 
complete processing. 


2. Make sure that there are no outstanding references to the specified queue. 


If a generic queue refers to the specified queue as a target execution queue, 
you must remove the specified queue from the list of target execution queues. 


If a logical queue refers to the specified queue, you must deassign the logical 
queue. 


If the specified queue is a generic queue, jobs that were entered initially 

on the generic queue and still exist on any of its target queues count as 
references to the specified queue. Before you can delete the specified queue, 
you must delete any jobs that were submitted originally to the specified queue 
and are executing on its target queues, or you must wait until these jobs have 
completed processing. 


3. To move jobs from the specified queue to another queue, use the SET ENTRY 
/REQUEUE or ASSIGN/MERGE commands. Any jobs that remain in the 
specified queue are deleted when the queue is deleted. 


4, Enter the DELETE/QUEUE command. 


/LOG 

/NOLOG (default) 

Controls whether the DELETE/QUEUVE command displays the name of each 
queue after it is deleted. 


DELETE/QUEUE 


Example 


$ INITIALIZE/QUEUE/DEFAULT=FLAG/START/ON=LPA0 LPAQ QUEUE 


$ STOP/QUEUE/NEXT LPAQ QUEUE 
$ DELETE/QUEUE LPAQ QUEUE 


In this example, the first command initializes and starts the printer queue 
LPAO_QUEUE. The STOP/QUEUE/NEXT command stops the queue. The 
DELETE/QUEUE command deletes the queue. 
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DELETE/QUEVUE/MANAGER 


Format 


Parameter 


Description 


Qualifier 


Example 
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Deletes a queue manager on a node or VAXcluster system. All queues and jobs 
managed by the specified queue manager are also deleted. You must first stop the 
queue manager. The /NAME_OF_MANAGER qualifier is required. 


Requires OPER (operator) and SYSNAM (system logical name) 
privileges. 


DELETE/QUEUVE/MANAGER/NAME_OF_MANAGER=name 
None. 


To delete a queue manager, use the following procedure: 


1. Stop the specified queue manager by using the STOP/QUEUE/MANAGER 
/CLUSTER/NAME_OF_MANAGER=name command. 


2. Enter the DELETE/QUEUE/MANAGER/NAME_OF_MANAGER command, 
specifying the queue manager name. 


/NAME_OF_MANAGERsstring 

Identifies the name of the queue manager to be deleted. The /NAME_OF_ 
MANAGER qualifier is required. The required name value may be up to 31 
characters long and may be a logical name. 


$ DELETE/QUEUE/MANAGER/ NAME OF MANAGER=BATCH MANAGER 


The DELETE/QUEUE/MANAGER/NAME_OF_MANAGER command in this 
example deletes the queue manager named BATCH_MANAGER. The command 
removes all references to the specified queue manager from the shared master file 


of the queue database and deletes the queue and journal files associated with the 
BATCH_MANAGER’s database. 


DELETE/SYMBOL 


DELETE/SYMBOL 


Format 


Parameter 


Description 


Qualifiers 


Examples 


Deletes one or all symbol definitions from a local or global symbol table. The 
/SYMBOL qualifier is required. 


DELETE/SYMBOL _[symbol-name] 


symbol-name 

Specifies the name of the symbol to be deleted. A name is required unless the 
/ALL qualifier is specified. The symbol-name parameter is incompatible with the 
/ALL qualifier. Symbol names can have from 1 to 255 characters. By default, 
the DELETE/SYMBOL command assumes that the symbol is in the local symbol 
table for the current command procedure. 


The DELETE/SYMBOL command deletes a symbol definition from a symbol 
table. If you do not specify either the global or local symbol table, the symbol 
is deleted from the local table. If you specify both the /GLOBAL and /LOCAL 
qualifiers, only the last specified qualifier is accepted. The /SYMBOL qualifier 
must always immediately follow the DELETE command name. 


/ALL 

Deletes all symbols from the specified table. If you do not specify either the 
/LOCAL or the /GLOBAL qualifier, all symbols defined at the current command 
level are deleted. The /ALL qualifier is incompatible with the symbol-name 
parameter. 


/GLOBAL 
Deletes the symbol from the global symbol table of the current process. 


/LOCAL (default) 
Deletes the symbol from the local symbol table of the current process. 


/ILOG 

/NOLOG (default) 

Controls whether an informational message listing each symbol being deleted is 
displayed. 


1. §$ DELETE/SYMBOL/ALL 


In this example, the DELETE/SYMBOL command deletes all symbol 
definitions at the current command level. 
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2. 


§ DELETE/SYMBOL/LOG KUDOS 
%DCL-I-DELSYM, LOCAL symbol KUDOS has been deleted 


In this example, the DELETE/SYMBOL command deletes the symbol KUDOS 
from the local symbol table for the current process. In addition, the /LOG 
qualifier causes an informational message, listing the symbol being deleted, 
to be displayed. 


$ DELETE/SYMBOL/GLOBAL PDEL 


In this example, the DELETE/SYMBOL command deletes the symbol named 
PDEL from the global symbol table for the current process. 


DEPOSIT 


Format 


Parameters 


DEPOSIT 


Replaces the contents of the specified locations in virtual memory and displays 
the new contents. 


The DEPOSIT command, together with the EXAMINE command, aids in 
debugging programs interactively. The DCL command DEPOSIT is similar to 
the DEPOSIT command of the OpenVMS Debugger. 


Requires user-mode read (R) and write (W) access to the virtual memory 
location whose contents you wish to change. 


DEPOSIT location=dataj,...] 


location 


Specifies the starting virtual address or range of virtual addresses (where the 
second address is larger than the first) whose contents are to be changed. A 
location can be any valid integer expression containing an integer value, a symbol 
name, a lexical function, or a combination of these entities. Radix qualifiers 
determine the radix in which the address is interpreted; hexadecimal is the 
initial default radix. Symbol names are always interpreted in the radix in which 
they were defined. The radix operators %X, %D, or %O can precede the location. 
A hexadecimal value must begin with a number (or be preceded by %X). 


The specified location must be within the virtual address space of the image 
currently running in the process. 


The DEPOSIT and EXAMINE commands maintain a pointer to a current memory 
location. The DEPOSIT command sets this pointer to the byte following the last 
byte modified; you can refer to this pointer by using a period (.) in subsequent 
EXAMINE and DEPOSIT commands. If the DEPOSIT command cannot deposit 
the specified data, the pointer does not change. The EXAMINE command does 
not change the value of the pointer. 


dataf,...] 

Specifies the data to be deposited into the specified locations. By default, the data 
is assumed to be in hexadecimal format; it is then converted to binary format and : 
is written into the specified location. 


If you specify more than one item, separate the items with commas (,). The 
DEPOSIT command writes the data in consecutive locations, beginning with the 
address specified. 


When non-ASCII data is deposited, you can specify each item of data using any 
valid integer expression. 


When ASCII data is deposited, only one item of data is allowed. All characters 
to the right of the equal sign are considered to be part of a single string. The 
characters are converted to uppercase, and all spaces are compressed. 
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When the DEPOSIT command completes, it displays both the virtual memory 
address into which data is deposited and the new contents of the location, as 
follows: 


address: contents 


If the specified address can be read from but not written to by the current access 
mode, the DEPOSIT command displays the original contents of the location. 

If the specified address can be neither read from nor written to, the DEPOSIT 
command displays asterisks (*) in the data field. The DEPOSIT command 
maintains a pointer at that location (at the byte following the last byte modified). 


If you specify a list of numeric values, some but not all of the values may be 
successfully deposited before an access violation occurs. If an access violation 
occurs while ASCII data is being deposited, nothing is deposited. 


Radix Qualifiers: The radix default for a DEPOSIT or EXAMINE command 
determines how the command interpreter interprets numeric literals. The 
initial default radix is hexadecimal; all numeric literals in the command line are 
assumed to be hexadecimal values. If a radix qualifier modifies the command, 
that radix becomes the default for subsequent EXAMINE and DEPOSIT 
commands, until another qualifier overrides it. For example: 


$ DEPOSIT/DECIMAL 900=256 
00000384: 256 


The DEPOSIT command interprets both the location 900 and the value 256 

as decimal. All subsequent DEPOSIT and EXAMINE commands assume that 
numbers you enter for addresses and data are decimal. Note that the DEPOSIT 
command always displays the address location in hexadecimal. 


Symbol values defined by = (assignment statement) commands are always 
interpreted in the radix in which they were defined. 


Note that hexadecimal values entered as deposit locations or as data to be 
deposited must begin with a numeric character (0 to 9). Otherwise, the command 
interpreter assumes that you have entered a symbol name and attempts symbol 
substitution. 


You can use the radix operators %X, %D, or %O to override the current default 
when you enter the DEPOSIT command. For example: 


$ DEPOSIT/DECIMAL %X900=10 


This command deposits the decimal value 10 in the location specified as 
hexadecimal 900. 


Length Qualifiers: The initial default length unit for the DEPOSIT command 
is a longword. If a list of data values is specified, the data is deposited into 
consecutive longwords beginning at the specified location. If a length qualifier 
modifies the command, that length becomes the default for subsequent EXAMINE 
and DEPOSIT commands, until another qualifier overrides it. If you specify data 
values that are longer than the specified length, an error occurs. 


Length qualifiers are ignored when ASCII values are deposited. 


Restriction on Placement of Qualifiers: The DEPOSIT command analyzes 
expressions arithmetically. Therefore, qualifiers, which must be preceded by a 
slash (/), must appear immediately after the command name to be interpreted 
correctly. 


Qualifiers 


Examples 


DEPOSIT 


/ASCII 
Indicates that the specified data is ASCII. 


Only one data item is allowed; all characters to the right of the equal sign (=) 
are considered to be part of a single string. Unless they are enclosed within 
quotation marks (“”), characters are converted to uppercase and multiple spaces 
are compressed to a single space before the data is written in memory. 


The DEPOSIT command converts the data to its binary equivalent before placing 
it in virtual memory. When you specify /ASCII, or when ASCII mode is the 
default, the location you specify is assumed to be hexadecimal. 


IBYTE 
Requests that data be deposited 1 byte at a time. 


/DECIMAL 
Indicates that the data is decimal. The DEPOSIT command converts the data to 
its binary equivalent before placing it in virtual memory. 


/HEXADECIMAL 
Indicates that the data is hexadecimal. The DEPOSIT command converts the 
data to its binary equivalent before placing it in virtual memory. 


/LONGWORD 
Requests that data be deposited a longword at a time. 


/OCTAL 
Indicates that the data is octal. The DEPOSIT command converts the data to its 
binary equivalent before placing it in virtual memory. 


/WORD 
Requests that the data be deposited one word at a time. 


1. $ RUN MYPROG 


$ EXAMINE %D2145876444 


7FE779DC: 0000000000 
$ DEPOSIT .=17 
TFE779DC: 0000000017 
$ CONTINUE 


The RUN command executes the image MYPROG.EXE; subsequently, 

Ctrl/Y interrupts the program. Assuming that the initial defaults of the 
/HEXADECIMAL and /LONGWORD qualifiers are in effect, the DEPOSIT 
command places a longword value 17 (23 decimal) in virtual memory location 
2145876444. 


Because the EXAMINE command sets up a pointer to the current memory 
location, which in this case is virtual address 2145876444, you can refer to 
this location with a period (.) in the DEPOSIT command. 


The CONTINUE command resumes execution of the image. 
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$ DEPOSIT/ASCII 2COQ0=FILE: NAME: TYPE: 
00002C00: FILE: NAME: TYPE:... 


In this example, the DEPOSIT command deposits character data at 
hexadecimal location 2C00 and displays the contents of the location after 
modifying it. Because the current default length is a longword, the response 
from the DEPOSIT command displays full longwords. The ellipsis ( ... ) 
indicates that the remainder of the last longword of data contains information 
that was not modified by the DEPOSIT command. 


$ EXAMINE 9C0 ! Look at Hex location 9C0 
000009C0: 8C037DB3 

$ DEPOSIT .=0 ! Deposit longword of 0 
000009C0: 00000000 

$ DEPOSIT/BYTE .=1 ! Put 1 byte at next location 
000009C4: 01 

$ DEPOSIT .+2=55 ! Deposit 55 next 


000009C7: 55 
$ DEPOSIT/LONG .=0C,0D,0E ! Deposit longwords 
000009C8: 0000000C 0000000D 0000000E 


The sequence of DEPOSIT commands in the above example illustrates how 
the DEPOSIT command changes the current position pointer. Note that after 
you specify the /BYTE qualifier, all data is deposited and displayed in bytes, 
until the /LONGWORD qualifier restores the system default. 


$ BASE=%X200 ! Define a base address 

$ LIST=BASE+%X40 ! Define offset from base 
$ DEPOSIT/DECIMAL LIST=1,22,333,4444 

00000240: 00000001 00000022 00000333 00004444 

$ EXAMINE/HEX LIST:LIST+0C ! Display results in hex 
00000240: 00000001 00000016 0000014D 0000115c 


The assignment statements define a base address in hexadecimal and a label 
at a hexadecimal offset from the base address. The DEPOSIT command reads 
the list of values and deposits each value into a longword, beginning at the 
specified location. The EXAMINE command requests a hexadecimal display 
of these values. 


DIAGNOSE (Alpha Only) 


DIAGNOSE (Alpha Only) 


On Alpha, the DIAGNOSE command invokes the DECevent management utility 
and selectively reports the contents of one or more event log files. For a complete 
description of the DECevent utility, see the OpenVMS System Management 
Utilities Reference Manual. 





Format 
DIAGNOSE [qualifier...] [filespec][,...] ¢ 
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DIFFERENCES 


Format 


Parameters 


Description 
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Compares the contents of two disk files and displays a listing of the records that 
do not match. 


DIFFERENCES _inputt-filespec [input2-filespec] 


inputt1-filespec 

Specifies the first file to be compared. The file specification must include a 
file name and a file type. The asterisk (*) and the percent sign (% ) wildcard 
characters are not allowed. 


input2-filespec 

Specifies the second file to be compared. Unspecified fields default to the 
corresponding fields in the input1-filespec parameter. The asterisk (*) and 
the percent sign (%) wildcard characters are not allowed. 


If you do not specify a secondary input file, the DIFFERENCES command uses 
the next lower version of the primary input file. 


Use the DIFFERENCES command to determine whether two files are identical 
and, if not, how they differ. The DIFFERENCES command compares the two 
specified files on a record-by-record basis and produces an output file that lists 
the DIFFERENCES, if any. 


The qualifiers for the DIFFERENCES command c can be categorized according to 
their functions, as follows: 


¢ Qualifiers that request the DIFFERENCES command to ignore data in each 
record: 


/COMMENT_DELIMITERS 
AIGNORE 


These qualifiers allow you to define characters that denote comments or to 
designate characters or classes of characters to ignore when comparing files. 
For example, you can have the DIFFERENCES command ignore extra blank 
lines or extra spaces within lines. 


By default, the DIFFERENCES command compares every character in each 
record. 


¢ Qualifiers that control the format of the information contained in the list of 
differences: 


/CHANGE_BAR 
AGNORE 
/MERGED 
/MODE 
/PARALLEL 
/SEPARATED 
/SLP 

/WIDTH 


Qualifiers 


DIFFERENCES 


By default, the DIFFERENCES command merges the differences it finds in 
the files being compared. It lists each record in the file that has no match in 
the other input file and then lists the next record that it finds that does have 
a match. 


By default, the DIFFERENCES command also supplies a line number 
with each listed record, and it lists the records with all designated ignore 
characters deleted. 


You can specify combinations of qualifiers to request an output listing that 
includes the comparison in more than one format. Note that SLP output is 
incompatible with all other types of output; parallel output can be generated 
only in ASCII mode. 


° Qualifiers that control the extent of the comparison: 


/MATCH 
/MAXIMUM_DIFFERENCES 
/WINDOW 


By default, the DIFFERENCES command reads every record in the master 
input file and looks for a matching record in the revision input file. A search 
for a match between the two input files continues until either a match is 
found or the ends of the two files are reached. Sections of the two files are 
considered a match only if three sequential records are found to be identical 
in each file. 


By default, DIFFERENCES command output is written to the current 
SYS$OUTPUT device. Use the /OUTPUT qualifier to request that the 
DIFFERENCES command write the output to an alternate file or device. 


The DIFFERENCES command terminates with an exit status. The following 
severity levels indicate the result of the comparison: 


SUCCESS Files are identical. 
INFORMATIONAL Files are different. 
WARNING User-specified maximum number of DIFFERENCES has 


been exceeded. 
ERROR Insufficient virtual memory to complete comparison. 


All severity levels other than SUCCESS indicate that the two input files are 
different. 


/CHANGE_BAR[=([change-char][,[NO]JNUMBER)})] 

Marks differences using the specified character. The /CHANGE_BAR qualifier 
displays output that depends on where the qualifier is placed. The following 
examples describe the result of /CHANGE_BAR qualifier placement. 


The following placement displays the latest version of input.file with the pound 
sign (#) preceding any lines that differ from the preceding version of input.file: 


$ DIFFERENCES input.file/CHANGE BAR=# 


The following placement displays input.file;2 with the pound sign (#) preceding 
any lines that differ from input.file;1: 


$ DIFFERENCES input.file;1 input.file;2 /CHANGE BAR=# 
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The following placement displays input.file;1 with the pound sign (#) preceding 
any lines that differ from input.file;2: 


$ DIFFERENCES input.file;1/CHANGE BAR=# input.file;2 


The following placement displays input.file;1 with the percent sign (%) preceding 
any lines that differ from input.file;2, and also displays input.file;2 with the pound 
sign (#) preceding any lines that differ from input.file;1: 


$ DIFFERENCES input.file;1/CHANGE BAR=% input.file;2/CHANGE BAR=# 


e If you do not specify a change bar character, the default is an exclamation 
point (!) for ASCII output. 


¢ If you specify hexadecimal or octal output (see the description of the (MODE 
qualifier), the change bar character is ignored and differences are marked by 
a “***CHANGE***” string in the record header. The keyword NONUMBER 
suppresses line numbers in the listing. 


e If neither the NUMBER nor the NONUMBER keyword is specified, the 
default is controlled by the //NOJNUMBER command qualifier. 


¢ If you specify only one option, you can omit the parentheses. 


e¢ If you use an exclamation point (!) as the specified character, you 
must enclose it in quotation marks (“”); for example, /CHANGE_ 
BAR=(“!’, NUMBER). 


/COMMENT_DELIMITER[=(character{,...])] | 
Ignores lines starting with a specified comment character. 


If the comment character is an exclamation point or semicolon (;), it can appear 
anywhere in the line and characters to the right of the character are ignored. 

If you specify just one character, you can omit the parentheses. Lowercase 
characters are automatically converted to uppercase unless they are enclosed 

in quotation marks. Nonalphanumeric characters (such as! and ,) must be 
enclosed in quotation marks. You can specify up to 32 comment characters by 
typing the character itself or one of the following keywords. (Keywords can be 
abbreviated provided that the resultant keyword is not ambiguous and has at 
least 2 characters; single letters are treated as delimiters.) 


Keyword Character 
COLON Colon (:) 
COMMA Comma (, ) 
EXCLAMATION Exclamation point (!) 
FORM_FEED Form feed 

LEFT Left bracket ([) 
RIGHT Right bracket (]) 
SEMI_COLON Semicolon (;) 
SLASH Slash (/) 

SPACE Space 

TAB Tab 


The /COMMENT_DELIMITER qualifier is used with or without the 
/IGNORE=COMMENTS qualifier to indicate which comments are to be ignored. 


DIFFERENCES 


If both the uppercase and lowercase forms of a letter are to be used as comment 
characters, the letter must be specified twice, once in uppercase and once in 
lowercase. If you do not include either a comment character or a keyword with 
the /COMMENT_DELIMITER qualifier, the DIFFERENCES command assumes 
a default comment character based on the file type. For some file types (.COB 
and .FOR), the default comment characters are considered valid delimiters only if 
they appear in the first column of a line. Multicharacter comment characters are 
not allowed. 


The following characters are the default comment delimiters for files with the 
specified file types: 


File Type Default Comment Character 


.B28, .B32, .BAS, .BLI ! 

.CBL, .CMD ! and ; 

.COB * or / in the first column 
.COM, .COR | 


.FOR ! anywhere and C, D, c, d in the first column 
-HLP ! 
.MAC, .MAR ; 
.R32, .REQ ! 


/EXACT 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string 
that must match the search string exactly and must be enclosed with quotation 
marks (“”). 


If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search 
mode is enabled when you set the search string with the Find (E1) key. 


/HIGHLIGHT[=keyword] 

/NOHIGHLIGHT (default) 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of 
highlighting you want when a search string is found. When a string is found, the 
entire line is highlighted. You can use the following keywords: BOLD, BLINK, 
REVERSE, and UNDERLINE. BOLD is the default highlighting. 


NiGNORE=(keyword....]) 

Inhibits the comparison of the specified characters, strings, or records; also 
controls whether the comparison records are output to the listing file as edited 
records or exactly as they appeared in the input file. If you specify only one 
keyword, you can omit the parentheses. The keyword parameter refers to either 
a character or a keyword. The first set of keywords determines what, if anything, 
is ignored during file comparison; the second set of keywords determines whether 
or not ignored characters are included in the output. The following keywords are 
valid options for the /IGNORE qualifier: 


Keyword Item Ignored 
BLANK_LINES Blank lines between data lines. 
CASE Case of the text being compared. 
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Keyword Item Ignored 


COMMENTS Data following a comment character. (Use the 
/COMMENT_DELIMITER qualifier to designate one 
or more nondefault comment delimiters.) 


FORM_FEEDS Form feed character. 


HEADER[=n] First n records of the file, beginning with a record 
whose first character is a form feed. The first record 
is not ignored if the only character it contains is a 
form feed. (N indicates the number of records and 
defaults to 2. A record with a single form feed is not 


counted.) 
SPACING Extra blank spaces or tabs within data lines. 
TRAILING_SPACES Space and tab characters at the end of a data line. 
Keyword Status of Ignored Items in Output 
EDITED . Omits ignored characters from the output records. 
EXACT Includes ignored characters in the output records. 
PRETTY Formats output records. 


Each data line is checked for COMMENTS, FORM_FEEDS, HEADER, and 
SPACING before it is tested for TRAILING_SPACES and then BLANK_LINES. 
Therefore, if you direct the DIFFERENCES command to ignore COMMENTS, 
TRAILING_SPACES, and BLANK_LINES, it ignores a record that contains 
several spaces or blank lines followed by a comment. 


By default, the DIFFERENCES command compares every character in each file 
and reports all differences. Also, by default, the DIFFERENCES command lists 
records in the output file with all ignored characters deleted. 


If you specify the /PARALLEL qualifier, output records are always formatted. To 
format output records, specify the following characters: 


Character Formatted Output 

Tab (Ctrl/D 1-8 spaces 

Return (Ctrl/M) <CR> 

Line feed (Ctrl/J) <LF> 

Vertical tab (Ctrl/K) <VT> 

Form feed (CtrI/L) <FF> 

Other nonprinting characters . (period) 

/MATCH=size 


Specifies the number of records that should indicate matching data after a 
difference is found. By default, after the DIFFERENCES command finds 
unmatched records, it assumes that the files once again match after it finds 
three sequential records that match. Use the /MATCH qualifier to override the 
default match size of 3. 


You can increase the /MATCH qualifier value if you feel that the DIFFERENCES 
command is incorrectly matching sections of the master and revision input files 
after it has detected a difference. 
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/MAXIMUM_DIFFERENCES=n 
Terminates the DIFFERENCES command after the specified number of 
unmatched records (specified with the n parameter) is found. 


The number of unmatched records is determined by finding the maximum number 
. of difference records for each difference section and adding them together. 


If the DIFFERENCES command reaches the maximum number of differences 
that you specify, it will output only those records that were detected before the 
maximum was reached. Also, it will output, at most, one listing format and 
return a warning message. 


By default, there is no maximum number of differences. All records in the 
specified input files are compared. 


/MERGED[=n] 

Specifies that the output file contain a merged list of differences with the specified 
number of matched records listed after each group of unmatched records. The 
value of the parameter n must be less than or equal to the number specified 

in the /MATCH qualifier. By default, the DIFFERENCES command produces a 
merged listing with one matched record listed after each set of unmatched records 
(that is, /MERGED=1). If the (MERGED, the /SEPARATED, or the /PARALLEL 
qualifier is not specified, the resulting output is merged, with one matched record 
following each unmatched record. 


Use the /MERGED qualifier to override the default value of the parameter n, or 
to include a merged listing with other types of output. 


/MODE=(radix{,...]) 

Specifies the format of the output. You can request that the output be formatted 
in one or more radix modes by specifying the following keywords, which may be 
abbreviated: ASCII (default), HEXADECIMAL, or OCTAL. If you specify only one 
radix, you can omit the parentheses. 


By default, the DIFFERENCES command writes the output file in ASCII. If you 
specify more than one radix, the output listing contains the file comparison in 
each specified radix. When you specify two or more radix modes, separate them 
with commas. 


If you specify the /PARALLEL or the /SLP qualifier, the (MODE qualifier is 
ignored for that listing form. 


/NUMBER (default) 
/NONUMBER 
Includes line numbers in the listing of DIFFERENCES. 


/OUTPUT[=filespec] 

Specifies an output file to receive the list of differences. By default, the output 
is written to the current SYS$OUTPUT device. If the filespec parameter is not 
specified, the output is directed to the first input file with a file type .DIF. The 
asterisk (*) and the percent sign (%) wildcard characters are not allowed. 


When you specify the /OUTPUT qualifier, you can control the defaults applied to 
the output file specification as described in the OpenVMS User’s Manual. The 
default output file type is .DIF. 


/PAGE[=keyword] 
- INOPAGE (default) 
Controls the display of difference information on the screen. 
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You can use the following keywords with the /PAGE qualifier: 


CLEAR_SCREEN Clears the screen before each page is displayed. 
SCROLL Displays information one line at a time. 
SAVE[=n] Enables screen navigation of information, where n is the 


number of pages to store. 


The /PAGE=SAVE qualifier allows you to navigate through screens of information. 
The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of 
information. When you use the /PAGE=SAVE qualifier, you can use the SaOWAnE 
keys to navigate through the information: 


Key Sequence Description 


Up arrow (fT), Ctrl/B Scroll up one line. 


Down arrow (| ) Scroll down one line. 

Left arrow (+ ) Scroll left one column. 

Right arrow (— ) Scroll right one column. 

Find (E1) Specify a string to find when the information is 
displayed. 

Insert Here (E2) Scroll right one half screen. 

Remove (E3) Scroll left one half screen. 

Select (E4) Toggle 80/132 column mode. 

Prev Screen (E5) Get the previous page of information. 

Next Screen (E6), Get the next page of information. 

Return, Enter, Space 

F10, Ctrl/Z - Exit. (Some utilities define these differently.) 

Help (F15) Display utility help text. 

Do (F16) Toggle the display to oldest/newest page. 

Ctrl/W Refresh the display. 


The /PAGE qualifier is not compatible with the /OUTPUT qualifier. 


/PARALLEL[=n] 
Lists the records with differences side by side. The value of the parameter n 
specifies the number of matched records to merge after each unmatched record; 


it must be a non-negative decimal number less than or equal to the number 
specified in the /MATCH qualifier. 


By default, the DIFFERENCES command does not list records after each list of 
unmatched records. Also by default, the DIFFERENCES command creates only a 
list of merged differences. 


/SEARCH='"string" 
Use with the /PAGE=SAVE qualifier to specify a string that you want to find in 
the information being displayed. Quotation marks are required for the /SEARCH 


_ qualifier, if you include spaces in the text string. 


You can also dynamically change the search string by pressing the Find key (E1) 
while the information is being displayed. Quotation marks are not required for a 
dynamic search. 
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/SEPARATED[=MASTER, REVISION] 
Lists sequentially only the records from the specified file that contain differences. 
Use the MASTER keyword to list the differences in the first input file specified; 

use the REVISION keyword to list the difference in the second input file specified. 


By default, the DIFFERENCES command creates only a merged list of 
differences. 


/SLP 

Requests that the DIFFERENCES command produce an output file suitable for 
input to the SLP editor. If you use the /SLP qualifier, you cannot specify any of 
the following output file qualifiers: /MERGED, /PARALLEL, /SEPARATED, or 
/CHANGE_BAR. 


Use the output file produced by the SLP qualifier as input to SLP to update the 
master input file, that is, to make the master input file match the revision input 
file. 


When you specify the /SLP qualifier and you do not specify the /OUTPUT 
qualifier, the DIFFERENCES command writes the output file to a file with the 
same file name as the master input file with the file type DIF. 


/WIDTH=n 

Specifies the width of the lines in the output file. The default is 132 characters. 
If output is written to the terminal, the (WIDTH qualifier is ignored and the 
terminal line width is used. 


Use the SET TERMINAL command to change the terminal line width. 


IWINDOWssize 

Searches the number of records specified by the size parameter, before a record 
is declared as unmatched. By default, the DIFFERENCES command searches to 
the ends of both input files before listing a record as unmatched. 


The window size is the minimum size of a differences section that will cause the 
DIFFERENCES command to lose synchronization between the two input files. 


IWRAP 

/NOWRAP (default) 

Use with the /PAGE=SAVE qualifier to limit the number of columns to the width 
of the screen and to wrap lines that extend beyond the width of the screen to the 
next line. 


The /NOWRAP qualifier extends lines beyond the width of the screen and can 
be seen when you use the scrolling (left and right) features provided by the 
/PAGE=SAVE qualifier. 


DCLI-165 


DIFFERENCES 


Examples 


1. 


$ DIFFERENCES EXAMPLE.TXT 
KREKKK KKK RR 

File DISK1:[GEORGE. TEXT ]EXAMPLE.TXT;2 
1 DEMONSTRATION 

2 OF V3.0 DIFFERENCES 

3 UTILITY 

* 


File DISK1: [GEORGE. TEXT ]EXAMPLE.TXT;1 
1  DEMONSTRETION 
2 OF VMS DIFFERENCES 
3. UTILITY 


REKKEKKKEKEEK 


Number of difference sections found: 1 
Number of difference records found: 2 
DIFFERENCES /MERGED=1- 
DISK1: [GEORGE. TEXT ] EXAMPLE. TXT; 2 
DISK1: [GEORGE. TEXT ] EXAMPLE. TXT; 1 


In this example, the DIFFERENCES command compares the contents of the two 
most recent versions of the file EXAMPLE.TXT in the current default directory. 
The DIFFERENCES command compares every character in every record and 
displays the results at the terminal. 


$ DIFFERENCES / PARALLEL/WIDTH=80/COMMENT_DELIMITER="V" EXAMPLE. TXT 


Number of difference sections found: 1 

Number of difference records found: 1 

DIFFERENCES / IGNORE= (COMMENTS ) /COMMENT DELIMITER=("V" ) /WIDTH=80 / PARALLEL- 
DISK1: [GEORGE. TEXT ]EXAMPLE . TXT; 2- 
DISK1: [GEORGE. TEXT ] EXAMPLE. TXT; 1 


The DIFFERENCES command compares the same files as in Example 1, but 
ignores all comments following the first “V” encountered by the DIFFERENCES 
command. The command also specifies that an 80-column parallel list of 
differences be displayed. 
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§ DIFFERENCES/WIDTH=80/MODE=(HEX, ASCII) EXAMPLE.TXT/CHANGE BAR 
KKKKKERREKRERE 
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT; 2 

1 ! DEMONSTRATION 

2 ! OF V3.0 DIFFERENCES 

3. UTILITY 


KEKKRKRKKKKKKK 
KEKKEKKKKEKKKEE 
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT;2 
RECORD NUMBER 1 (00000001) LENGTH 14 (0000000E) +***CHANGE*** 
204E 4F495441 5254534E 4F4D4544 DEMONSTRATION .. 000000 
RECORD NUMBER 2 (00000002) LENGTH 19 (00000013) ***CHANGE*** 
4F455245 46464944 20302E33 5620464F OF V3.0 DIFFEREN 000000 


534543 CES vi aie 07663860. 6-0% 000010 
RECORD NUMBER 3 (00000003) LENGTH 7 (00000007) 
595449 4¢495455 UTILITY......... 000000 


RREKEKRKEKKEKE 


Number of difference sections found: 1 

Number of difference records found: 2 

DIFFERENCES /WIDTH=80/MODE=(HEX, ASCII) 
DISK1: [GEORGE. TEXT ]EXAMPLE.TXT;2/CHANGE BAR- 
DISK1: [GEORGE. TEXT] EXAMPLE. TXT; 1 


The DIFFERENCES command compares the same files as in Example 1, but 
lists the differences in both hexadecimal and ASCII formats. The command also 
specifies that default change bars be used in the output. The default change bar 
notation for the hexadecimal output is ***CHANGE***, For the ASCII output, 
the default change bar character is the exclamation point. 


$ DIFFERENCES/OUTPUT BOSTON: :DISK2:TEST.DAT OMAHA: :DISK1:[PGM]TEST.DAT 


The DIFFERENCES command compares two remote files and displays any 
differences found. The first file is TEST.DAT on remote node BOSTON. 
The second file is also named TEST.DAT on remote node OMAHA. The 
DIFFERENCES output is located in the file DISK1:[PGM]TEST.DIF. 
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Parameter 


Description 
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Provides a list of files or information about a file or group of files. 


Requires execute (E) access to look up files you know the names of, read 
(R) access to read or list a file or to use a file name with the asterisk (*) 
and the percent sign (%) wildcard characters to look up files. 


DIRECTORY  [filespecf,...]] 
DIRECTORY/FTP  directorySpec 


filespecf[,...] 
Specifies one or more files to be listed. The syntax of a file specification 
determines which files will be listed, as follows: 


¢ If you do not enter a file specification, the DIRECTORY command lists all 
versions of the files in the current default directory. 


¢ If you specify only a device name, the DIRECTORY command uses your 
default directory specification. 


e Whenever the file specification does not include a file name, a file type, and a 
version number, all versions of all files in the specified directory are listed. 


e Ifa file specification contains a file name or a file type, or both, and no version 
number, the DIRECTORY command lists all versions. 


e Ifa file specification contains only a file name, the DIRECTORY command 
lists all files in the current default directory with that file name, regardless of 
file type and version number. 


¢ Ifa file specification contains only a file type, the DIRECTORY command lists 
all files in the current default directory with that file type, regardless of file 
name and version number. 


The asterisk (*) and the percent sign (% ) wildcard characters can be used in 
the directory specification, file name, file type, or version number fields of a file 
specification to list all files that satisfy the components you specify. If you specify 
more than one file, separate the file specifications with either commas (,) or plus 
signs (+). 


directorySpec 

Specifies the standard DECnet remote file specification. Use a quoted file string 
to preserve the case (for case-sensitive systems such as UNIX) and to identify a 
foreign device/directory specification. See the /FTP qualifier for more information. 


The DIRECTORY command lists the files contained in a directory. When you use 
certain qualifiers with the command, additional information is displayed, along 
with the names of the files. 
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$ DIFFERENCES/WIDTH=80/MODE=(HEX,ASCII) EXAMPLE.TXT/CHANGE BAR 
RRKKKEKKKKEKER 
File DISK1:[GEORGE.TEXT]EXAMPLE.TXT; 2 

1 ! DEMONSTRATION 

2 ! OF V3.0 DIFFERENCES 

3 UTILITY 


KRKKKEEKKERE 
RRR KR ERE EK 
File DISK1:[GEORGE. TEXT] EXAMPLE. TXT; 2 
RECORD NUMBER 1 (00000001) LENGTH 14 (0000000E) ***CHANGE*** 
204E 4F495441 5254534E 4F4D4544 DEMONSTRATION .. 000000 
RECORD NUMBER 2 (00000002) LENGTH 19 (00000013) ***CHANGE*** 
4B455245 46464944 20302E33 5620464F OF V3.0 DIFFEREN 000000 


534543 CES... .cccceoee ~- 000010 
RECORD NUMBER 3 (00000003) LENGTH 7 (00000007) 
595449 4C495455 UTILITY......+4. 000000 


RREKEKKEKKKKEKEK 


Number of difference sections found: 1 

Number of difference records found: 2 

DIFFERENCES /WIDTH=80/MODE=(HEX,ASCII) 
DISK1: [GEORGE. TEXT ] EXAMPLE. TXT; 2/CHANGE BAR- 
DISK1: [GEORGE. TEXT ] EXAMPLE. TXT; 1 ~ 


The DIFFERENCES command compares the same files as in Example 1, but 
lists the differences in both hexadecimal and ASCII formats. The command also 
specifies that default change bars be used in the output. The default change bar 
notation for the hexadecimal output is ***CHANGE***, For the ASCII output, 
the default change bar character is the exclamation point. 


$ DIFFERENCES/OUTPUT BOSTON: :DISK2:TEST.DAT OMAHA: :DISK1:[PGM] TEST. DAT 


The DIFFERENCES command compares two remote files and displays any 
differences found. The first file is TEST.DAT on remote node BOSTON. 
The second file is also named TEST.DAT on remote node OMAHA. The 
DIFFERENCES output is located in the file DISK1:[PGM]TEST.DIF. 
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Provides a list of files or information about a file or group of files. 


Requires execute (E) access to look up files you know the names of, read 
(R) access to read or list a file or to use a file name with the asterisk (*) 
and the percent sign (%) wildcard characters to look up files. 


DIRECTORY  [filespecf,...]] 
DIRECTORY/FTP  directorySpec 


filespec{,...] 
Specifies one or more files to be listed. The syntax of a file specification 
determines which files will be listed, as follows: 


e If you do not enter a file specification, the DIRECTORY command lists all 
versions of the files in the current default directory. 


e If you specify only a device name, the DIRECTORY command uses your 
default directory specification. 


¢ Whenever the file specification does not include a file name, a file type, and a 
version number, all versions of all files in the specified directory are listed. 


¢ Ifa file specification contains a file name or a file type, or both, and no version 
number, the DIRECTORY command lists all versions. 


e Ifa file specification contains only a file name, the DIRECTORY command 
lists all files in the current default directory with that file name, regardless of 
file type and version number. 


e Ifa file specification contains only a file type, the DIRECTORY command lists 
all files in the current default directory with that file type, regardless of file 
name and version number. 


The asterisk (*) and the percent sign (%) wildcard characters can be used in 
the directory specification, file name, file type, or version number fields of a file 
specification to list all files that satisfy the components you specify. If you specify 
more than one file, separate the file specifications with either commas (, ) or plus 
signs (+). 


directorySpec 

Specifies the standard DECnet remote file specification. Use a quoted file string 
to preserve the case (for case-sensitive systems such as UNIX) and to identify a 
foreign device/directory specification. See the /FTP qualifier for more information. 


The DIRECTORY command lists the files contained in a directory. When you use 
certain qualifiers with the command, additional information is displayed, along 
with the names of the files. 


Qualifiers 


DIRECTORY 


The output of the DIRECTORY command depends on certain formatting qualifiers 
and their defaults. These qualifiers are as follows: /COLUMNS, /DATE, /FULL, 
/OWNER, /PROTECTION, and /SIZE. However, the files are always listed in 
alphabetical order, with the highest numbered versions listed first. 


In studying the qualifiers and the capabilities they offer, watch for qualifiers that 
work together and for qualifiers that override other qualifiers. For example, if 
you specify the /FULL qualifier, the system cannot display all the information 

in more than one column. Thus, if you specify both the /COLUMNS and /FULL 
qualifiers, the number of columns you request is ignored. 


You can also select other languages and formats that have been defined on your 
systems with international date and time formatting routines available in the 
run-time library. See the OpenVMS RTL Library (LIB$) Manual. 


/ACL 

Controls whether the access control list (ACL) is displayed for each file. By 
default, the DIRECTORY command does not display the ACL for each file. Access 
control entries (ACEs) that were created with the hidden option are displayed 
only if the SECURITY privilege is turned on. The /ACL qualifier overrides the 
/COLUMNS qualifier. 


For further information, see the OpenVMS Guide to System Security. 


/BACKUP 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /BACKUP qualifier selects files according to the dates of their most recent 
backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/BEFORE[=time] 

Selects only those files dated prior to the specified time. You can specify time 
as an absolute time, as a combination of absolute and delta times, or as one 

of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 


/BRIEF (default) 

Displays only a file’s name, type, and version number. The brief format lists the 
files in alphabetical order from left to right on each line, in descending version 
number order. You can use the /ACL, /DATE, /FILE_ID, /FULL, /NOHEADING, 
/OWNER, /PROTECTION, /SECURITY, and /SIZE qualifiers to expand a brief 
display. . 


/BY_OWNER[=uic] 
Selects only those files whose owner user identification code (UIC) matches the 
specified owner UIC. The default UIC is that of the current process. 


Specify the UIC by using standard UIC format as described in the OpenVMS 
User’s Manual. 
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For further information, see the OpenVMS Guide to System Security. 


/COLUMNS=n 

Specifies the number of columns in a brief display. The default is four. However, 
you can request as many columns as you like, restricted by the value of the 
/WIDTH qualifier. The /COLUMNS qualifier is incompatible with the /ACL, 
/FULL, and /SECURITY qualifiers. 


The number of columns actually displayed depends on the amount of information 
requested for each column and the display value of the /WIDTH qualifier. The 
system displays only as many columns as can fit within the default or specified 
display width, regardless of how many columns you specify with the (COLUMNS 
qualifier. 


The DIRECTORY command truncates long file names only when you specify 
more than one column and you have asked for additional information to be 
included in each column. The default file name size is 19 characters. Use the 
/WIDTH qualifier to change the default. When a file name is truncated, the 
system displays one less character than the file name field size and inserts a 
vertical bar in the last position. For example, if the file name is SHOW_QUEUE_ 
CHARACTERISTICS, and if you requested DIRECTORY to display both file 
name and size in each column, the display for that file would be SHOW_QUEUE_ 
CHARACT | 120. 


/CREATED (default) 

Modifies the time value specified with the (BEFORE or the /SINCE qualifier. The 
/CREATED qualifier selects files based on their dates of creation. This qualifier is 
incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which 
also allow you to select files according to time attributes. If you specify none of 
these four time qualifiers, the default is the /CREATED qualifier. 


/DATE[=option] 

/NODATE (default) 

Includes the creation, last modification, expiration, backup, effective, or recording 
date for each specified file; the default is the /NODATE qualifier. If you use the 
/DATE qualifier without an option, the creation date is provided. Possible options 
are as follows: 


Option Description 
ALL Specifies all optional dates in the following order: creation, last 
modification, expiration, backup, effective, and recording. 
BACKUP Specifies the last backup date. 
_ CREATED Specifies the creation date. 
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EFFECTIVE Specifies the effective date the contents are valid (ISO 9660). 
EXPIRED Specifies the expiration date. 

MODIFIED Specifies the last modification date. 

RECORDING _ Specifies the recording date on the media (ISO 9660). 


/EXACT 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string 
that must match the search string exactly and must be enclosed with quotation 
marks (“”). 


DIRECTORY 


If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search 
mode is enabled when you set the search string with the Find (E1) key. - 


/EXCLUDE=(filespecI,...]) 

Excludes the specified files from the DIRECTORY command. You can include 

a directory but not a device in the file specification. The asterisk (*) and 

the percent sign (% ) wildcard characters are allowed in the file specification. 
However, you cannot use relative version numbers to exclude a specific version. If 
you specify only one file, you can omit the parentheses. 


/EXPIRED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /EXPIRED qualifier selects files according to their expiration dates. (The 
expiration date is set with the SET FILE/EXPIRATION_DATE command.) 
The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time qualifiers, the default is the 
/CREATED qualifier. 


/FILE_ID 
Controls whether the file identification (FID) number is displayed. By default, 
the FID is not displayed unless the /FULL qualifier is specified. 


[FTP 

Invokes the directory (dir or ls) operation of the FTP utility. The DIRECTORY 
/FTP command writes a listing of the contents of the specified remote directory to 
the local host over a TCP/IP connection by invoking the FTP utility. 


/FULL 
Displays the following information for each file: 


File name 

File type 

Version number 

File identification number (FID) 
Number of blocks used 

Number of blocks allocated 

File owner’s user identification code (UIC) 
Date of creation 

Date last modified and revision number 
Date of expiration 

Date of last backup 

Date of effective usage 

Date of recording on media 

File organization 

Shelved state 

File attributes 

Record format 

Record attributes 

RMS attributes 

Journaling information 

File protection 

Access control list (ACL) 

Value of the stored semantics tag (where applicable) 
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/GRAND_TOTAL 

Displays only the totals for all files and directories that have been specified. 
Suppresses both the per-directory total and individual file information. (See the 
/TRAILING qualifier for information on displaying directory totals.) 


/HEADING 

/INOHEADING 

Controls whether heading lines consisting of a device description and directory 
specification are printed. The default output format provides this heading. When 
the /NOHEADING qualifier is specified, the display is in single-column format 
and the device and directory information appears with each file name. The 
/NOHEADING qualifier overrides the /COLUMNS qualifier. 


The combination of the /NOHEADING and /NOTRAILING qualifiers is useful in 
command procedures where you want to create a list of complete file specifications 
for later operations. 


/HIGHLIGHT[=keyword] 

/NOHIGHLIGHT (default) 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of 
highlighting you want when a search string is found. When a string is found, the 
entire line is highlighted. You can use the following keywords: BOLD, BLINK, 
REVERSE, and UNDERLINE. BOLD is the default highlighting. _ 


/MODIFIED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /MODIFIED qualifier selects files according to the dates on which they were 
last modified. This qualifier is incompatible with the /BACKUP, /CREATED, 
and /EXPIRED qualifiers, which also allow you to select files according to time 
attributes. If you specify none of these four time modifiers, the default is the 
/CREATED qualifier. 


/OUTPUT[=filespec] 

/INOOUTPUT 

Controls where the output of the command is sent. By default, the display is 
written to the current SYS$OUTPUT device. The asterisk (*) and the percent 
sign (%) wildcard characters are not allowed. 


If you enter the /OUTPUT qualifier with a partial file specification (for example, 
/OUTPUT=[JONES]), DIRECTORY is the default file name and LIS the default 
file type. If you enter the /(NOOUTPUT qualifier, output is suppressed. 


If the output will be written to a file in the same directory, the output file name 
will appear in the directory listing. 


/OWNER 
/NOOWNER (default) 
Controls whether the file owner’s user identification code (UIC) is listed. 


The default size of the owner field is 20 characters. If the file owner’s UIC 
exceeds the length of the owner field, the information will be truncated. The size 
of this field can be altered by specifying /(WIDTH=OWNER, along with a value 
for the owner field. For more information, see the description of the /WIDTH 
qualifier. 
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/PAGE[=keyword] 
/NOPAGE (default) 
Controls the display of directory information on the screen. 


You can use the following keywords with the /PAGE qualifier: 


CLEAR SCREEN Clears the screen before each page is displayed. 
SCROLL Displays information one line at a time. 
SAVE[=n] Enables screen navigation of information, where n is the 


number of pages to store. 


The /PAGE=SAVE qualifier allows you to navigate through screens of information. 
The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of 
information. When you use the /PAGE=SAVE qualifier, you can use the following 
keys to navigate through the information: 


Key Sequence Description 


Up arrow (f ), Ctrl/B Scroll up one line. 


Down arrow (| ) Scroll down one line. 

Left arrow (+ ) Scroll left one column. 

Right arrow (—) Scroll right one column. 

Find (E1) Specify a string to find when the information is 
displayed. 

Insert Here (E2) Scroll right one half screen. 

Remove (E3) Scroll left one half screen. 

Select (E4) Toggle 80/132 column mode. 

Prev Screen (E5) Get the previous page of information. 

Next Screen (E6), Get the next page of information. 

Return, Enter, Space 

F10, Ctrl/Z Exit. (Some utilities define these differently.) 

Help (F15) Display utility help text. . 

Do (F16) Toggle the display to oldest/newest page. 

Ctrl/w Refresh the display. 


The /PAGE qualifier is not compatible with the /OUTPUT qualifier. 


/PRINTER 

Puts the display in a file and queues the file to SYS$PRINT for printing under 
the name given by the /OUTPUT qualifier. If you do not specify the /OUTPUT 
qualifier, output is directed to a temporary file named DIRECTORY.LIS, which is 
queued for printing and then is deleted. 


/PROTECTION 
/NOPROTECTION (default) 
Controls whether the file protection for each file is listed. 
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/SEARCH='"string" 

Use with the /PAGE=SAVE qualifier to specify a string that you want to find in 
the information being displayed. Quotation marks are required for the /SEARCH 
qualifier, if you include spaces in the text string. 


You can also dynamically change the search string by pressing the Find key (E1) 
while the information is being displayed. Quotation marks are not required for a 
dynamic search. 


/SECURITY 

Controls whether information about file security is displayed; using the 
/SECURITY qualifier is equivalent to using the /ACL, /OWNER, and 
/PROTECTION qualifiers together. ACEs that were created with the hidden 
option are displayed only if the SECURITY privilege is turned on. 


For further information, see the OpenVMS. Guide to System Security. 


/SELECT=(keywordj,...]) 
Allows you to select files for display. Choose one of the following keywords: 


ACL Displays files that have an associated ACL or 
NOACL files that do not (NOACL keyword). 
' FILE=(option{,...]) Displays portions of the file specification. 


The /SELECT=FILE qualifier is used to turn 
off specific portions by explicit or implicit 
specification of the options. Possible options 
are: 


[NOJNODE 

. [NOJDEVICE 
[NO]JDIRECTORY 
[NOJNAME 
[NO]TYPE 
[NOJVERSION 


/SELECT=FILE qualifier cannot be used with 
the /FULL qualifier. 


ONLINE Displays files that are online or shelved. 
NOONLINE 


SHELVABLE Displays files that are shelvable or not 
NOSHELVABLE shelvable. 
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SIZE=(option[....]) Displays files according to their size. Possible 
options are: 


Option Description 


MAXIMUM=n Displays files that 
have fewer blocks 
than the value of n, 
which defaults to 
1,073,741,823. Use 
with MINIMUM=n 
to specify a size 
range for files to be 
displayed. 

MINIMUM=n Displays files that 
have blocks equal 
to or greater than 
the value of n. Use 
with MAXIMUM=n 
to specify a size 
range for files to be 


displayed. 
(MINIMUMEn, Displays files whose 
MAXIMUM=n) block size falls 


within the specified 
MINIMUM and 
MAXIMUM range. 


By default, file selection is based on other criteria. 


/SHELVED_STATE 
Displays whether the file is shelved or online. 


/SINCE[=time] 

Selects only those files dated after the specified time. You can specify time as 
an absolute time, as a combination of absolute and delta times, or as one of 
the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual. 
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/SIZE[=option] 

/NOSIZE (default) 

Displays the size in blocks of each file. If you omit the option parameter, the 
default lists the file size in blocks used (USED). Specify one of the following 
options: 


ALL Lists the file size both in blocks allocated and blocks used. 
ALLOCATION Lists the file size in blocks allocated. 
USED Lists the file size in blocks used. 


The size of this field can be altered by supplying the size value of the (WIDTH 
qualifier. 


/TIME[=option] 

/NOTIME (default) 

The same as the /DATE qualifier: includes the backup, creation, expiration, or 
modification time for each specified file; the default is the /NOTIME qualifier. 
If you use the /TIME qualifier without an option, the creation time is provided. 
Possible options are as follows: 


Option Description 

ALL Specifies creation, expiration, backup, and last modification 
times. 

BACKUP ' Specifies the last backup time. 

CREATED Specifies the creation time. 

EFFECTIVE Specifies the effective time the contents are valid. 

EXPIRED Specifies the expiration time. 


MODIFIED Specifies the last modification time. 
RECORDING Specifies the recording time on the media. 


TOTAL | 
Displays only the directory name and total number of files. 


By default, the output format is determined by the /BRIEF qualifier, which gives 
this total but also lists all the file names, file types, and their version numbers. 


[TRAILING 

/NOTRAILING 

Controls whether trailing lines that provide the following summary information 
are displayed: 


¢ Number of files listed 
¢ Total number of blocks used per directory 
e Total number of blocks allocated 


¢ Total number of directories and total blocks used or allocated in all directories 
(only if more than one directory is listed) 


By default, the output format includes most of this summary information. The 
/SIZE and /FULL qualifiers determine more precisely what summary information 
is included. 


Examples 
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When used alone, the /TRAILING qualifier lists the number of files in the 
directory. When used with the /SIZE qualifier, the /TRAILING qualifier lists the 
number of files and the number of blocks (displayed according to the option of the 
/SIZE qualifier, FULL or ALLOCATION). When used with the /FULL qualifier, 
the /TRAILING qualifier lists the number of files as well as the number of blocks 
used and allocated. If more than one directory is listed, the summary includes 
the total number of directories, the total number of blocks used, and the total 
number of blocks allocated. 


/VERSIONS=n 
Specifies the number of versions of a file to be listed. The default is all versions 
of each file. A value less than 1 is not allowed. 


IWIDTH=(keyword....]) 
Formats the width of the display. If you specify only one keyword, you can omit 
the parentheses. Possible keywords are as follows: 


DISPLAY=n — Specifies the total width of the display as an integer in the 
range 1 to 256 and defaults to zero (setting the display width 
to the terminal width). If the total width of the display exceeds 
the terminal width, the information will be truncated. 

FILENAME=n — Specifies the width of the file name field; defaults to 19 
characters. If you request another piece of information to be 
displayed along with the file name in each column, file names 
that exceed the n parameter cause the line to wrap after the file 
name field. (See the ‘COLUMNS qualifier.) 

OWNER=n Specifies the width of the owner field; defaults to 20 characters. 
If the owner’s user identification code (UIC) exceeds the length 
of the owner field, the information will be truncated. 

SIZE=n Specifies the width of the size field; defaults to 6 characters 

on systems prior to OpenVMS Version 6.0; the default is 7 
characters on OpenVMS Version 6.0 systems or higher. If the 
file size exceeds the length of the size field, the field is filled 
with asterisks. 


/WRAP 

/NOWRAP (default) 

Use with the /PAGE=SAVE qualifier to limit the number of columns to the width 
of the screen and to wrap lines that extend beyond the width of the screen to the 
next line. 


The /NOWRAP qualifier extends lines beyond the width of the screen and can 
be seen when you use the scrolling (left and right) features provided by the 
/PAGE=SAVE qualifier. 


1. $ DIRECTORY AVERAGE. * 
Directory DISKSDOCUMENT: [MALCOLM] 
AVERAGE . EXE; 6 AVERAGE . FOR; 6 AVERAGE .LIS;4 AVERAGE.OBJ; 12 


Total of 4 files. 


In this example, the DIRECTORY command lists all files with the file name 
AVERAGE and any file type. 
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2. 


$ DIRECTORY/SIZE=USED/DATE=CREATED/VERSIONS=1/PROTECTION AVERAGE 
Directory DISKSDOCUMENT: [MALCOLM] 


AVERAGE .EXE: 6 
AVERAGE . FOR; 6 
AVERAGE .LIS; 4 
AVERAGE .OBJ; 6 


19-APR-1995 15:43:02.10 (RE,RE,RWED,RE) 
19-APR-1995 10:29:53.37 (RE,RE,RWED,RE) 
19-APR-1995 16:27:27.19 (RE,RE,RWED,RE) 
19-APR-1995 16:27:44.23 (RE,RE,RWED,RE) 


bB ON a 


Total of 4 files, 15 blocks. 


In this example, the DIRECTORY command lists the number of blocks used, 
the creation date, and the file protection code for the highest version number 
of all files named AVERAGE in the current directory. 


$ DIRECTORY/FULL DISK$GRIPS_2:[VMS.TV]DEMO.EXE 
Directory DISKSGRIPS 2:[VMS.TV] 


DEMO. EXE; 1 File ID: (36,11,0) 

Size: 390/390 Owner: [0,0] 

Created: 12-NOV-1995 11:45:19.00 

Revised: 14-DEC-1995 15:45:19.00 (34) 

Expires: <None specified> 

Backup: 28-NOV-1995 04:00:12.22 

Effective: <None specified> 

Recording: <None specified> 

File organization: Sequential 

Shelved state: Online 

File attributes: Allocation: 390, Extend: 0, Global buffer count: 0, 
Version limit: 0, Backups disabled, Not shelvable 


Record format: Fixed length 512 byte records 
Record attributes: None 
RMS attributes: None 


Journaling enabled: None 
File protection: System:RE, Owner:RE, Group:RE, World:RE 
Access Cntrl List: None 


Total of 1 file, 390/390 blocks. 
The example illustrates the DIRECTORY/FULL command. 


$ DIRECTORY/VERSIONS=1/COLUMNS=1 AVERAGE. * 


The DIRECTORY command in this example lists only the highest version of 
each file named AVERAGE in the current default directory. The format is 
brief and restricted to one column. Heading and trailing lines are provided. 


$ DIRECTORY BLOCK%%% 


The DIRECTORY command in this example locates all versions and types of 
files in the default device and directory whose names begin with the letters 
BLOCK and end with any three additional characters. The default output 
format is brief, four columns, with heading and trailing lines. 


$ DIRECTORY/EXCLUDE=(AVER.DAT;*,AVER.EXE;*) [*...]JAVER 


The DIRECTORY command in this example lists and totals all versions and 
types of files named AVER in all directories and subdirectories on the default 
disk, except any files named AVER.DAT and AVER.EXE. 
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$ DIRECTORY/SIZE=ALL FRESNO: :DISK1: [TAYLOR] *.COM 


The DIRECTORY command in this example lists all versions of all files with 
the file type COM in the directory TAYLOR on node FRESNO and device 
DISK1. The listing includes the file size both in blocks used and in blocks 
allocated for each file. 


$ DIRECTORY- 
_$ /MODIFIED/SINCE=14-DEC-1995:01:30/SIZE=ALL/OWNER- 
_$ /PROTECTION/OUTPUT=UPDATE/PRINTER [A*] 


The DIRECTORY command in this example locates all files that have been 
modified since 1:30 a.m. on December 14, 1995, and that reside on the default 
disk in all directories whose names begin with the letter A. It formats the 
output to include all versions, the size used and size allocated, the date last 
modified, the owner, and the protection codes. The output is directed to a file 
named UPDATE.LIS, which is queued automatically to the default printer 
queue and then is deleted. 


$ DIRECTORY/SHELVED STATE 
Directory MYDISK: [SMITH] 


MYFILE. TXT; 2 Online 
NOT_SHELVED.TXT;1 Online 
SHELVED. TXT Shelved 


Total of 3 files. 


The DIRECTORY command in this example lists all the files in a directory 
and shows whether a file is shelved, online, or remote. 
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DISABLE AUTOSTART 


Format 


Parameters 


Description 


Qualifiers 
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Disables the autostart feature on a node for all autostart queues managed by the 
specific queue manager. By default, this command uses the /QUEUES qualifier. 


Requires OPER (operator) privileges. 


For more information on autostart queues, see the chapter on batch and print 
queues in the OpenVMS System Manager’s Manual. 


DISABLE AUTOSTART[/QUEUES] 


None. 


The DISABLE AUTOSTART/QUEUES command notifies the queue manager to 
perform the following tasks on the affected node: 


¢ Mark all of the queue manager’s autostart queues as “stop pending” in 
preparation for a planned shutdown. 


e Prevent any of the queue manager’s autostart queues from failing over to the 
node. 


¢ Upon completion of any jobs currently executing on any of that queue 
manager’s autostart queues, force the queue to fail over to the next available 
node in the queue’s failover list (if any) on which autostart is enabled. (For 
information on failover lists for autostart queues, see the /AUTOSTART_ON 
qualifier for the INITIALIZE/QUEUVE command.) 


Autostart queues on the node that do not have a failover list, or for which no 
failover node is enabled for autostart, are stopped upon completion of any current 
jobs. These stopped queues remain activated for autostart. The queue manager 
will restart these stopped autostart queues when the ENABLE AUTOSTART 
command is entered for the affected node or a node to which the queue can fail 
over. 


By default the command affects the node on which it is entered. Specify the 
/ON_NODE qualifier to disable autostart on a different node. 


The DISABLE AUTOSTART/QUEUES command is included in the node 
shutdown command procedure SHUTDOWN.COM. If you shutdown a node 
without using SHUTDOWN.COM, and the node is running autostart queues, you 
might want to enter the DISABLE AUTOSTART/QUEUES command first. 


The DISABLE AUTOSTART/QUEUES command only affects autostart queues. 


/NAME_OF_MANAGER=name 

Specifies the name of the queue manager controlling the autostart queues you 
want to disable. The qualifier allows the autostart feature to be used differently 
for different sets of queues. 


Examples 


DISABLE AUTOSTART 


If the /NAME_OF_MANAGER qualifier is omitted, the default queue manager 
name SYS$QUEUE_MANAGER is used. For more information on multiple queue 
managers, see the OpenVMS System Manager’s Manual. 


/ON_NODE=nodename 
Specifies a node in a VMScluster system. Use this qualifier to disable autostart 
on a node other than the one from which you enter the command. 


/QUEUES 
Specifies that autostart is to be disabled for queues. (This qualifier is used by 
default.) 


1. 


$ INITIALIZE/QUEUE/BATCH/START/AUTOSTART ON=SATURN:: BATCH 1 
$ ENABLE AUTOSTART/QUEUES 


$ DISABLE AUTOSTART/QUEUES 


In this example, the INITIALIZE/QUEUE command creates an autostart 
queue BATCH_1, capable of executing on node SATURN. The /START 
qualifier activates the queue for autostart. The ENABLE/AUTOSTART 
/QUEUES command (executed on node SATURN) enables autostart on the 
node, causing the queue (and any other active autostart queues on the node)to 
begin executing jobs. 


The DISABLE AUTOSTART command (executed on node SATURN) stops 
autostart queues on the node, and prevents any queues from failing over to 
the node. 


This command only affects queues managed by the default queue manager 
SYS$QUEUE_MANAGER because the /NAME_OF_MANAGER qualifier is 
not specified. 


Because BATCH_1 is set up to run only on one node, the queue cannot fail 
over to another node and therefore is stopped. However, the queue remains 
active for autostart and will be started when the ENABLE AUTOSTART 
command is entered for node SATURN. No START/QUEUE command is 
needed to restart BATCH_1 unless autostart of the queue is deactivated with 
the STOP/QUEUE/NEXT or STOP/QUEUE/RESET command. 


$DISABLE AUTOSTART/QUEUES/ON_NODE=JADE 


The DISABLE AUTOSTART/QUEUES command in this example disables 
autostart on the VMScluster node JADE. This command can be entered from 
any node in the cluster. 
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Format 


Parameters 


Description 


Qualifier 


Examples 
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Breaks the connection between a physical terminal and a virtual terminal. After 
the physical terminal is disconnected, both the virtual terminal and the process 
using it remain on the system. 


Requires that your physical terminal is connected to a virtual terminal. 


DISCONNECT 


None. 


Use the DISCONNECT command to disconnect a physical terminal from a virtual 
terminal and its associated process. The virtual terminal and the process remain 
on the system, so you can use the CONNECT command to reconnect to the 
process later. (For more information about virtual terminals and how to connect 
to them, see the description of the CONNECT command.) To terminate a process 
connected to a virtual terminal, use the LOGOUT command. 


After you are disconnected from a virtual terminal, you can use the physical 
terminal to log in again. 


You can use the DISCONNECT command only if your physical terminal is 
connected to a virtual terminal. 


/CONTINUE 

/NOCONTINUE (default) 

Controls whether the CONTINUE command is executed in the current process 
just before connecting to another process. This procedure permits an interrupted 
image to continue processing after the disconnection until the process needs 
terminal input or attempts to write to the terminal. At that point, the process 
waits until the physical terminal is reconnected to the virtual terminal. 


1. $ DISCONNECT 


This command disconnects a physical terminal from a virtual terminal, but 
does not log the process out. Now you can use the physical terminal to log in 
again. 


2. $ RUN PAYROLL 


$ DISCONNECT/CONTINUE 


In this example, the RUN command is entered from a physical terminal 
that is connected to a virtual terminal. After the image PAYROLL.EXE is 
interrupted, the DISCONNECT command disconnects the physical and the 
virtual terminals without logging out the process. The /CONTINUE qualifier 
allows the image PAYROLL.EXE to continue to execute until the process 


DISCONNECT 


needs terminal input or attempts to write to the terminal. At that point, 
the process waits until the physical terminal is reconnected to the virtual 
terminal. However, you can use the physical terminal to log in again and 
perform other work. 
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Format 


Parameter 


Description 
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Closes a mounted disk or tape volume for further processing and deletes the 
logical name associated with the device. 


Requires the GRPNAM (group logical name) and SYSNAM (system logical 
name) privileges to dismount group and system volumes. 


DISMOUNT  device-namef[:] 


device-name[:] ; 

Name of the device containing the volume—either a logical name or a physical 
name. If a physical name is specified, the controller defaults to A and the unit 
defaults to 0. 


If the volume currently mounted on the device is a member of a disk or tape 
volume set, all volumes in the set are dismounted, unless the /UNIT qualifier is 
specified. 


The DISMOUNT command (which invokes the $DISMOU system service) checks 
for conditions that prevent a Files—11 volume from dismounting. The conditions 
fall into the following categories: 


¢ Installed swap and page files 

¢ Installed images 

e Devices spooled to the volume 

e Open user files (any files not falling into one of the first three categories) 


If the DISMOUNT command does not find any of these conditions, it performs the 
following operations: 


¢ Removes the volume from the user’s list of mounted volumes, deletes the 
logical name (if any) associated with the volume, and decrements the mount 
count. 


¢ Ifthe mount count equals zero after being decremented, the DISMOUNT 
command marks the volume for dismounting. 


As soon as the volume is idle, that is, after the DISMOUNT command has 
determined that no user has any open files on the volume, the DISMOUNT 
command marks a Files—11 volume for dismounting, and dismounts the 
volume soon. 


e Ifthe mount count does not equal zero after being decremented, the 
DISMOUNT command does not mark the volume for dismount (because 
the volume must have been mounted shared). In this case, the total effect for 
the issuing process is that the process is denied access to the volume and the » 
logical name is deleted. 


Qualifiers 


-DISMOUNT 


¢ After a volume is dismounted, nonpaged pool is returned to the system. 
Paged pool is also returned if the volume was mounted using the /GROUP or 
/SYSTEM qualifiers. 


If the DISMOUNT command does find open files or any other condition that 
prevents the volume from dismounting, it does not mark the volume for 
dismounting. Instead, the DISMOUNT command displays a message indicating 
that the volume cannot be dismounted, followed by messages indicating the 
conditions that exist and the number of instances of each condition. 


The /OVERRIDE=CHECKS qualifier allows a volume to be marked for 
dismounting despite open files or other conditions. For example, marking a 
volume for dismounting prevents any new files from being opened. Also, when a 
volume is marked for dismounting, file-system caches are flushed. This activity is 
especially important when the system is shutting down and the file-system caches 
must be written to the disk. 


If a volume is part of a Files—11 volume set and the /UNIT qualifier is not 
specified, the entire volume set will be dismounted. 


If the volume was mounted with the /SHARE qualifier, it is not actually 
dismounted until all users who mounted it dismount it or log out. However, 
the DISMOUNT command deletes the logical name associated with the device. 


If the device was allocated with an ALLOCATE command, it remains allocated 
after the volume is dismounted with the DISMOUNT command. If the device 
was implicitly allocated by the MOUNT command, the DISMOUNT command 
deallocates it. 


If the volume was mounted with the /GROUP or the /SYSTEM qualifier, it is 

dismounted even if other users are currently accessing it. The GRPNAM and 
SYSNAM user privileges are required to dismount group and system volumes, 
respectively. 


/ABORT 

Requires volume ownership or the user privilege VOLPRO (volume 
protection) to use this qualifier with a volume that was mounted with 
neither the /GROUP nor the /SYSTEM qualifier. Additionally requires the 
user privilege SHARE if the volume is mounted privately by a process 
other than the process issuing the DISMOUNT command. 


Specifies that the volume is to be dismounted, regardless of who mounted it. The 
primary purpose of the /ABORT qualifier is to terminate mount verification. The 
DISMOUNT/ABORT command also cancels any outstanding I/O requests. If the 
volume was mounted with the /SHARE qualifier, the /ABORT qualifier causes the 
volume to be dismounted for all of the users who mounted it. 


/CLUSTER 

Dismounts a volume throughout a dual-architecture VMScluster system. If you 
specify DISMOUNT/CLUSTER, the DISMOUNT command checks for open files 
or other conditions that will prevent a Files—11 volume on the local node from | 
dismounting. If the DISMOUNT command does not find any open files or other 
conditions, it checks for conditions on all other nodes in the VMScluster. If the 
DISMOUNT command finds one of the conditions on any node, it displays an 
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error message identifying the device and the nodes on which the error occurred, 
followed by an error message indicating open files or other conditions on the 
volume. | 


After the DISMOUNT command successfully dismounts the volume on the local 
node, it dismounts the volume on every other node in the existing VMScluster 
environment. If the system is not a member of a cluster, the /CLUSTER qualifier 
has no effect. 


/OVERRIDE=CHECKS 

Marks a Files—11 volume for dismounting even if files are open on the volume. 
If you specify DISMOUNT/OVERRIDE=CHECKS, the DISMOUNT command 
displays messages indicating any open files or other conditions that prevent 
dismounting, immediately followed by a message indicating that the volume has 
been marked for dismounting. 


A substantial amount of time can pass between the time you enter the 
DISMOUNT/OVERRIDE=CHECKS command and the completion of the dismount 
operation. Always wait for the dismount to complete before you remove the 
volume. (To verify that the dismount has completed, enter the SHOW DEVICES 
command.) Note that the final phase of volume dismounting occurs in the 

file system, and all open files on the volume must be closed before the actual 
dismount can be done. Note also that the file system cannot dismount a volume 
while any known file lists associated with it contain entries. 


/UNIT 
Dismounts only one volume of a volume set on the specified device. By default, 
all volumes in a set are dismounted. 


Note 


Avoid dismounting the root volume of a volume set, because it contains 
the master file directory (MFD). It may be impossible to access files on a 
volume set if the MFD is not accessible. 


/UNLOAD 

/NOUNLOAD 

Determines whether the device on which the volume is mounted is physically 
unloaded. If you specify the DISMOUNT command without the /UNLOAD or » 
the /NOUNLOAD qualifier, the qualifier that you specified with the MOUNT 
command (either /UNLOAD or /NOUNLOAD) determines whether the volume is 
unloaded physically. 


1. $ MOUNT MTAO: PAYVOL TAPE 


$ DISMOUNT TAPE 


The MOUNT command in this example mounts the tape whose volume 
identification is PAYVOL on the device MTAO: and assigns the logical name 
TAPE to the device. By default, the volume is not shareable. The 


DISMOUNT 


DISMOUNT command releases access to the volume, deallocates the device, 
and deletes the logical name TAPE. 


$ MOUNT/SHARE DBA3: DOC FILES 


$ DISMOUNT DBA3: 


The MOUNT command in this example mounts the volume labeled DOC_ 
FILES on the device DBA3. Other users can enter MOUNT commands 

to access the device. The DISMOUNT command shown in this example 
deaccesses the device for the process issuing the command. If other users still 
have access to the volume, the volume remains mounted for their process or 
processes. 


$ DISMOUNT/NOUNLOAD DMA2: 


The DISMOUNT command in this example dismounts the volume; the 
/NOUNLOAD qualifier requests that the volume remain in a ready state. 


$ MOUNT/BIND=PAYROLL DMA1:,DMA2: PAYROLLO1,PAYROLLO2 


$ DISMOUNT/UNIT DMA2: 


The MOUNT command in this example mounts PAYROLL, a two-volume set. 
The DISMOUNT command dismounts only PAYROLLO2, leaving PAYROLLO1 
accessible. Note that because the master file directory (MFD) for the volume 
set is on the root volume, you should not dismount the root volume (in this 
case, PAYROLLO1) of the volume set. 


$ DISMOUNT $10SDJA100 

SDISM-W-CANNOTDMT, $10SDJA100: cannot be dismounted 
SDISM-W-INSWPGFIL, 4 swap or page files installed on volume 
$DISM-W-SPOOLEDEV, 3 devices spooled to volume 
$DISM-W-INSTIMAGE, 7 images installed on volume 
$DISM-W-USERFILES, 6 user files open on volume 


The DISMOUNT command in this example displays the open files and other 
conditions that prevent device $10$DJA100 from dismounting. 


$ DISMOUNT/CLUSTER $10SDJA100 

$DISM-W-RMTDMTFAIL, $10SDJA100: failed to dismount on node SALT 
¢DISM-W-FILESOPEN, volume has files open on remote node 
$DISM-W-RMTDMTFAIL, $10$DJA100: failed to dismount on node PEPPER 
tDISM-W-FILESOPEN, volume has files open on remote node 
SDISM-W-CANNOTDMT, $10SDJA100: cannot be dismounted 


The DISMOUNT command in this example displays messages identifying 
device $10$DJA100 and nodes SALT and PEPPER on which errors occurred 
followed by messages indicating open files on the volume. 


DCLI-187 


DUMP 


DUMP 


Format 


Parameter 


Description 


DCLI-188 


Displays the contents of a file, a directory, a disk volume, a magnetic tape volume, _ 
or a CD-ROM volume in decimal, hexadecimal, octal format, ASCII, or formatted 
data structures. 


DUMP filespec [,...] 


filespec {....] 
Specifies the file or name of the device being dumped. 


If the specified device is not a disk, a tape, or a network device, or if the device 
is mounted with the /FOREIGN qualifier, the file specification must contain only 
the device name. 


If the specified device is a network device, a disk device, or a tape device that is 
mounted without the /FOREIGN qualifier, the file specification can contain the 
asterisk (*) and the percent sign (%) wildcard characters. 


Files—11 C/D format standards have been implemented on mounted and foreign 
mounted volumes. 


By default, the DUMP command formats the output both in ASCII characters 
and in hexadecimal longwords. You can specify another format for the dump by 
using a radix qualifier ((OCTAL, /DECIMAL, or /HEXADECIMAL) or a length 
qualifier (/BYTE, /WORD, or /LONGWORD). 


Dumping Files 

If the input medium is a network device, a disk device, or a tape device that is 
mounted without the /FOREIGN qualifier, the DUMP command operates on files. 
You can dump files by either records or blocks. The asterisk (*) and the percent 
sign (%) wildcard character specifications can be used to select a group of files for 
processing. 


Dumping Volumes 

If the input medium is not a disk or a tape device, or if it is mounted with the 
/FOREIGN qualifier, the DUMP command operates on the input device as a 
non-file-structured (NFS) medium. Disk devices are dumped by 512-byte logical 
blocks. Other devices are dumped by physical blocks. No repositioning of the 
input medium occurs; therefore, consecutive blocks on a tape can be dumped by a 
single DUMP command. 


If you have LOG_IO (logical I/O) privilege, you can dump random blocks on a 
Files—11 volume. For example, by using the /BLOCKS qualifier, you could dump 
block 100 on the system disk. 


Reading Dumps 
The ASCII representation is read left to right. The hexadecimal, decimal, and 
octal representations are read right to left. 


Qualifiers 


DUMP 


Specifying Numeric Qualifier Values 

The numeric values for the /BLOCKS, /RECORDS, and /NUMBER qualifiers 
can be specified either as decimal numbers or with a leading %X, %O, or %D to 
signify hexadecimal, octal, or decimal numbers respectively. For example, the 
following are all valid ways to specify decimal value 24: 


24 

%X18 
%O030 
%D24 


/ALLOCATED 
Includes in the dump all blocks allocated to the file. (By default, the dump does 
not include blocks following the end-of-file [EOF].) 


You can specify the /ALLOCATED qualifier if the input is a disk that is mounted 
without the /FOREIGN qualifier. The /ALLOCATED and /RECORDS qualifiers 
are mutually exclusive. 


/BLOCKS[=(option,...])] 
Dumps the specified blocks one block at a time, which is the default method for 
all devices except network devices. 


Block numbers are specified as integers relative to the beginning of the file. 
Typically, blocks are numbered beginning with 1. If a disk device is mounted 
using the /FOREIGN qualifier, blocks are numbered beginning with zero. Select a 


_ range of blocks to be dumped by specifying one of the following options: 


START:n Specifies the number of the first block to be dumped; the default 
is the first block. 
END:n Specifies the number of the last block to be dumped; the default 


is the last block or the end-of-file (EOF) block, depending on 
whether you have specified the /ALLOCATED qualifier. 


COUNT:n Specifies the number of blocks to be dumped. The COUNT 
option provides an alternative to the END option; you cannot 
specify both. 


If you specify only one option, you can omit the parentheses. 

The /BLOCKS and /RECORDS qualifiers are mutually exclusive. 

Use the /BLOCKS qualifier to dump random blocks from Files—11 volumes. This 
procedure requires LOG-IO (logical I/O) privilege. 


/IBYTE 
Formats the dump in bytes. The /BYTE, /LONGWORD, and /WORD qualifiers 
are mutually exclusive. The default format is composed of longwords. 


/DECIMAL 
Dumps the file in decimal radix. The /DECIMAL, /HEXADECIMAL (default), and 
/OCTAL qualifiers are mutually exclusive. 


/DESCRIPTOR[=option{,...] 
Dumps the specified Files—11 volumes. If /NOFORMAT is used, the format is in 
blocks. 
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/DIRECTORY 

Dumps data blocks of the specified file as formatted on-disk structures of either 
Files—11 On-Disk Structure Level 1 or On-Disk Structure Level 2 directory 
records, ISO 9660, or High Sierra directory records. 


/EXACT 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string 
that must match the search string exactly and must be enclosed with quotation 
marks (“ ”). 


If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search 
mode is enabled when you set the search string with the Find (E1) key. 


/FILE_HEADER 
Dumps each data block that is a valid Files—11 header in Files—11 header format 
rather than in the selected radix and length formats. 


/FORMATTED (default) 

/NOFORMATTED 

Dumps the file header in Files—11 format; the /NOFORMATTED qualifier dumps 
the file header in octal format. This qualifier is useful only when the /HEADER 
qualifier is specified. 


/HEADER 

Dumps the file header and access control list (ACL). To dump only the file header, 
and not the file contents, also specify /BLOCK=(COUNT:0). The /HEADER 
qualifier is invalid for devices mounted using the /FOREIGN qualifier. 


Use the /FORMATTED qualifier to control the format of the display. 


You can use the /FILE_HEADER qualifier with the /HEADER qualifier to have 
Files—11 file headers printed in an interpreted representation. 


By default, the file header is not displayed. 


/HEXADECIMAL (default) 
Dumps the file in hexadecimal radix. The /DECIMAL, /HEXADECIMAL (default), 
and /OCTAL qualifiers are mutually exclusive. 


/HIGHLIGHT[=keyword] 

/NOHIGHLIGHT (default) 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of 
highlighting you want when a search string is found. When a string is found, the 
entire line is highlighted. You can use the following keywords: BOLD, BLINK, 
REVERSE, and UNDERLINE. BOLD is the default highlighting. 


ADENTIFIER=file-id 

Dumps the file selected by the file identification (FID) number from the specified 
volume. For further information, see the /FILE_ID qualifier from the DCL 
command, DIRECTORY. 


/LONGWORD (default) 
Formats the dump in longwords. The /BYTE, /LONGWORD, and /WORD 
qualifiers are mutually exclusive. 


/MEDIA_FORMAT 
Dumps a data structure assuming ISO 9660 (CD-ROM) or High Sierra (CDROM_ 
HS) media format that is a foreign mounted device. 


DUMP 


/NUMBER[=n] 

Specifies how byte offsets are assigned to the lines of output. If you specify the 
/NUMBER qualifier, the byte offsets increase continuously through the dump, 
beginning with n; if you omit the /NUMBER qualifier, the first byte offset is zero. 
By default, the byte offset is reset to zero at the beginning of each block or record. 


IOCTAL 
Dumps the file in octal radix. The (DECIMAL, /HEXADECIMAL (default), and 
/OCTAL qualifiers are mutually exclusive. 


/OUTPUT[=filespec] 

Specifies the output file for the dump. If you do not specify a file specification, 
the default is the file name of the file being dumped and the file type .DMP. If 
the /OUTPUT qualifier is not specified, the dump goes to SYS$OUTPUT. The 
/OUTPUT and /PRINTER qualifiers are mutually exclusive. 


/PAGE[=keyword] 
/NOPAGE (default) 
Controls the display of dump information on the screen. 


You can use the following keywords with the /PAGE qualifier: 


CLEAR_SCREEN Clears the screen before each page is displayed. 
SCROLL Displays information one line at a time. 
SAVE[=n] Enables screen navigation of information, where n is the 


number of pages to store. 


The /PAGE=SAVE qualifier allows you to navigate through screens of information. 
The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of 
information. When you use the /PAGE=SAVE qualifier, you can use the following 
keys to navigate through the information: 


Key Sequence Description 


Up arrow (f ), Ctrl/B Scroll up one line. 


Down arrow (|) Scroll down one line. 

Left arrow (+) Scroll left one column. 

Right arrow (— ) Scroll right one column. 

Find (E1) Specify a string to find when the information is 
displayed. 

Insert Here (E2) Scroll right one half screen. 

Remove (E3) Scroll left one half screen. 

Select (E4) Toggle 80/132 column mode. 

Prev Screen (E5) Get the previous page of information. 

Next Screen (E6), Get the next page of information. 

Return, Enter, Space 

F10, Ctrl/Z Exit. (Some utilities define these differently.) 

Help (F15) Display utility help text. 

Do (F16) Toggle the display to oldest/newest page. 

Ctrl/W Refresh the display. 


The /PAGE qualifier is not compatible with the /OUTPUT qualifier. 
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/PATH_TABLE 
Dumps data blocks in Files—11 path-table format. 


/PRINTER 

Queues the dump to SYS$PRINT i in a file named with the file name of the file 
being dumped and the file type .DMP. If the /PRINTER qualifier is not specified, 
the dump goes to SYS$OUTPUT. The asterisk (*) and the percent sign (%) 
wildcard characters are not allowed. The /OUTPUT and /PRINTER qualifiers are 
mutually exclusive. 


/RECORDS[=(option],...])] 
Dumps the file a record at a time rather than a block at a time. (By default, 
input is dumped one block at a time for all devices except network devices.) 


Records are numbered beginning with 1. 


Select a range of records to be dumped by specifying one of the following options: 


START:n Specifies the number of the first record to be dumped; the 
default is the first record. 

END:n Specifies the number of the last record to be dumped; the default 
is the last record of the file. 

COUNT:n Specifies the number of records to be dumped. The COUNT 
option provides an alternative to the END option; you cannot 
specify both. 


If you specify only one option, you can omit the parentheses. 


If you specify the (RECORDS qualifier, you cannot specify the /ALLOCATED or 
the /BLOCKS qualifier. 


/SEARCH="string" 

Use with the /PAGE= SAVE qualifier to specify a string that you want to find in 
the information being displayed. Quotation marks are required for the /SEARCH 
qualifier, if you include spaces in the text string. 


You can also dynamically change the search string by pressing the Find key (E1) 
while the information is being displayed. Quotation marks are not required for a 
dynamic search. 


/VALIDATE_HEADER 
Verifies /DIRECTORY records for Files—11. 


/WIDTH=n 
Formats the dump output into 80 or 132 columns by specifying n as either 80 or 
132. 


/WORD 
Formats the dump in words. The /BYTE, /LONGWORD, and /WORD qualifiers 
are mutually exclusive. 


WRAP 

/NOWRAP (default) 

Use with the /PAGE=SAVE qualifier to limit the number of columns to the width 
of the screen and to Wap lines that extend beyond the width of the screen to the 
next line. 


Examples 


DUMP 


The /NOWRAP qualifier extends lines beyond the width of the screen and can 
be seen when you use the scrolling (left and right) features provided by the 
/PAGE=SAVE qualifier. 


E, 


$ DUMP TEST.DAT 

Dump of file DISK0:[NORMAN]TEST.DAT;1 on 14-DEC-1994 15:43:26.08 

File ID (3134,818,2) End of file block 1 / Allocated 3 

Virtual block number 1 (00000001), 512 (0200) bytes 
706D6173 20612073 69207369 68540033 3.This is a samp 000000 
73752065 62206F74 20656C69 6620656C le file to be us 000010 
61786520 504D5544 2061206E 69206465 ed in a DUMP exa 000020 


00000000 00000000 0000002E 656C706D mple............ 000030 
00000000 00000000 00000000 00000000 ...... ec ececeeee 000040 
00000000 00000000 00000000 00000000 ......ececeeeeas 000050 
00000000 00000000 00000000 00000000 ........eeeeneee 000060 
00000000 00000000 00000000 00000000 .......ceceeeees 000150 
00000000 00000000 00000000 00000000 ..........eeeeee 0001F0 


The DUMP command displays the contents of TEST.DAT both in hexadecimal 
longword format and in ASCII beginning with the first block in the file. 


) 


$ DUMP TEST.DAT/OCTAL/BYTE 
Dump of file DISKO:[NORMAN]TEST.DAT;1 on 14-DEC-1994 15:45:33.58 
File ID (74931,2,1) End of file block 1 / Allocated 3 
Virtual block number 1 (00000001), 512 (0200) bytes 

151 040 163 151 150 124 000 063 3.This i 000000 

160 155 141 163 040 141 040 163 s a samp 000010 

040 145 154 151 146 040 145 154 le file 000020 

163 165 040 145 142 040 157 164 to be us 000030 

040 141 040 156 151 040 144 145 ed ina 000040 

141 170 145 040 120 115 125 104 DUMP exa 000050 

377 377 000 056 145 154 160 155 mple.... 000060 


000 000 000 000 000 000 000 000 ........ 000070 
000 000 000 000 000 000 000 000 ........ 000100 
000 000 000 000 000 000 000 000 ........ 000110 
000 000 000 000 000 000 000 000 ........ 000760 
000 000 000 000 000 000 000 000 ........ 000770 


The DUMP command displays the image of the file TEST.DAT, formatted both 
in octal bytes and in ASCII characters beginning with the first block. 


$ DUMP NODE3: :DISK2: [STATISTICS ]RUN1.DAT 


This command line dumps the file RUN1.DAT that is located at remote node 
NODES. The default DUMP format will be used. 
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$ DUMP/HEADER/BLOCK=COUNT=0 SYS$SYSTEM: DATASHARE .EXE 
Dump of file SYSSSYSTEM:DATASHARE.EXE on 12-NOV-1994 16:06:46.75 


File ID (16706,59,0) 


Header area 
Identification area offset: 
Map area offset: 
Access control area offset: 
Reserved area offset: 
Extension segment number: 
Structure level and version: 
File identification: 
Extension file identification: 
VAX RMS attributes 
Record type: 
File organization: 
Record attributes: 
Record size: 
Highest block: 
End of file block: 
End of file byte: 
Bucket size: 
Fixed control area size: 
Maximum record size: 
Default extension size: 
Global buffer count: 
Directory version limit: 
File characteristics: 
Map area words in use: 
Access mode: 
File owner UIC: 
File protection: 
Back link file identification: 
Journal control flags: 
Active recovery units: 
Highest block written: 


Identification area 
File name: 
Revision number: 
Creation date: 
Revision date: 
Expiration date: 
Backup date: 


Map area 
Retrieval pointers 


Count: 411 LBN: 


Checksum: 


End of file block 410 / Allocated 411 


File Header 


40 
100 

255 

255 

0 

2, 

(16706, 59,0) 
(0,0,0) 


Fixed 

Sequential 

<none specified> 
512 

411 

410 

414 

0 

0 

512 

0 

0 

0 

Contiguous best try 
3 


0 

[1,4] 

S:RWED, O:RWED, G:RE, W: 
(7149,80,0) 

<none specified> 

None 

411 


DATASHARE. EXE 

1 

12-AUG-1994 14:06:49.84 
12-AUG-1994 14:06:53.20 
<none specified> 

<none specified> 


1297155 


30710 


In this example, the DUMP command dumps the file header of the specified 
file. Since this file is recorded on Files—11 ODS-2 9660 media, the file header 
is displayed in a Files—11 File Header format. Imbedded on the Files—11 


Header is a VAX RMS attributes block. 


DUMP 


5. § DUMP/HEADER/BLOCK=COUNT=0 DISKSGRIPS 2:[000000 ]AAREADME .TXT; 
Dump of file DISKSGRIPS 2:[000000)AAREADME.TXT;1 on 15-DEC-1994 
10:07:29.70 


File ID (4,6,0) End of file block 29 / Allocated 29 
ISO 9660 File Header 


Length of Directory Record: 
Extended Attribute Length: 
Location of Extent (LSB/MSB): 


Data Length of File Section (LSB/MSB): 


Recording Date and Time 
File Flags 

Interleave File Unit size: 
Interleave Gap size: 


Volume Sequence # of extent (LSB/MSB): 


File Identifier Field Length: 
File Identifier: 
System Use 


48 

1 

312/312 

14640/14640 

10-DEC-1994 16:22:30 GMT(0) 
RECORD, PROTECTION 

0 


0 

1/1 

14 

AAREADME .TXT; 1 


5458542E 454D4441 45524141 0£010000 01000018 001E1610 100B5930 39000000 


DOV crccecccceves AAREADME.TXT 000000 


SOrrererrr errr rere rere rer eee 000020 


Extended Attribute record 


Owner Identification (LSB/MSB): 
Group Identification (LSB/MSB): 


00313B 


7/7 
246/246 


Access permission for classes of users S:R, O:R, G:RE, W:RE 


File Creation Date/Time: 
File Modification Date/Time: 
File Expiration Date/Time: 
File Effective Date/Time: 
Record Format 

Record Attributes 

Record Length (LSB/MSB): 
System Identifier: 

System Use 

Extended Attribute Version: 
Escape Sequence record length: 


Application Use Length (LSB/MSB): 


Application Use 


VAX RMS attributes 
Record type: 
File organization: 
Record attributes: 
Record size: 
Highest block: 
End of file block: 
End of file byte: 
Bucket size: 
Fixed control area size: 
Maximum record size: 
Default extension size: 
Global buffer count: 
Directory version limit: 


5-OCT-1994 14:17:49.29 GMT(0) 
6-NOV-1994 16:22:30.96 GMT(0) 
00-00-0000 00:00:00.00 GmMT(0) 
00-00-0000 00:00:00.00 GMT(0) 
Fixed 

CRLF 

80/80 


1 
0 
0/0 


Fixed 

Sequential 

Implied carriage control 
80 

29 

29 

304 

0 

0 

80 


ooo 


The DUMP/HEADER command dumps the file header of the specified file. 
Since this file is recorded on ISO 9660 media, the file header is displayed 
in the format of an ISO 9660 File Header, and, since this file contains an 
optional ISO 9660 Extended Attribute Record (XAR), it is also displayed. 
Finally, as with all DUMP/HEADER requests, VAX RMS attributes are 
displayed. 


DCLI-195 


EDIT/ACL 


EDIT/ACL 


Invokes the access control list (ACL) editor, which creates or modifies an access 
control list for a specified object. The /ACL qualifier is required. For a complete 
description of the ACL Editor, see the OpenVMS System Management Utilities 
Reference Manual or the OpenVMS Guide to System Security. 


Format 
EDIT/ACL object-spec 
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Description 


Qualifiers 


EDIT/EDT 


Invokes EDT, an interactive text editor. The /EDT qualifier is required. 
EDIT/EDT _ filespec 


filespec 
Specifies the file to be created or edited using EDT. If the file does not exist, it is 
created by EDT. 


EDT does not provide a default file type when creating files; if you do not include 
a file type, it is null. The file must be a disk file on a Files—11 formatted volume. 


The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


EDT creates or edits text files. You can use EDT to enter or edit text in three 
modes: keypad, line, or nokeypad. Keypad editing, which is screen-oriented, is 
available on VT300-series, VT200-series, VT100, and VT52 terminals. A screen- 
oriented editor allows you to see several lines of text at once and move the cursor 
throughout the text in any direction. Line editing operates on all terminals. In 
fact, if you have a terminal other than a VT300-series, VT200-series, VT100, 

or VT52, line editing is the only way you can use EDT. You might prefer line 
editing if you are accustomed to editing by numbered lines. Nokeypad mode is a 
command-oriented screen editor available on VT300-series, VT200-series, VT100, 
and VT52 terminals. You can use line mode and nokeypad mode to redefine keys 
for use in keypad mode. 


When you invoke EDT, you are in line mode by default. If you are editing an 
existing file, EDT displays the line number and text for the first line of the file. If 
you are creating a new file, EDT displays the following message: 


Input file does not exist 

[EOB] 

In either case, EDT then displays the line mode prompt, which is the asterisk 
C*). 

For complete details on the EDT editor, see the OpenVMS EDT Reference Manual. 


/COMMAND[=filespec] 

/NOCOMMAND 

Determines whether or not EDT uses a startup command file. The /COMMAND 
file qualifier should be followed by an equal sign (=) and the specification of 
the command file. The default file type for command files is .EDT. The asterisk 
(*) and the percent sign (%) wildcard characters are not allowed in the file 
specification. 
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The following command line invokes EDT to edit a file named MEMO.DAT and 
specifies that EDT use a startup command file named XEDTINI.EDT: 


$ EDIT/COMMAND=XEDTINI.EDT MEMO.DAT 


If you do not include the /COMMAND=command file qualifier, EDT looks for the 
EDTSYS logical name assignment. If EDTSYS is not defined, EDT processes the 
systemwide startup command file SYS$LIBRARY:EDTSYS.EDT. If this file does 

not exist, EDT looks for the EDTINI logical name assignment. If EDTINI is not 

defined, EDT looks for the file named EDTINI.EDT in your default directory. If 

none of these files exists, EDT begins your editing session in the default state. 


To prevent EDT from processing either the systemwide startup command file or 
the EDTINI.EDT file in your default directory, use the /NOCOMMAND qualifier 
as follows: 


$ EDIT/EDT/NOCOMMAND MEMO. DAT 


/CREATE (default) 

/NOCREATE 

Controls whether EDT creates a new file when the specified input file is not 
found. 


Normally, EDT creates a new file to match the input file specification if it 
cannot find the requested file name in the specified directory. When you use the 
/NOCREATE qualifier in the EDT command line and type a specification for a 
file that does not exist, EDT displays an error message and returns to the DCL 
command level as follows: 


$ EDIT/EDT/NOCREATE NEWFILE.DAT 
Input file does not exist 


/JOURNAL[=journal-file] 

/NOJOURNAL 

Determines whether EDT keeps a journal during your editing session. A journal 
contains a record of the keystrokes you enter during an editing session. The 
default file name for the journal is the same as the input file name. The default 
file type is JOU. The /JOURNAL qualifier enables you to use a different file 
specification for the journal. 


The following command line invokes EDT to edit a file named MEMO.DAT and 
specifies the name SAVE.JOU for the journal: 


$ EDIT/EDT/JOURNAL=SAVE MEMO.DAT 


If you are editing a file from another directory and want the journal to be located 
in that directory, you must use the /JOURNAL qualifier with a file specification 
that includes the directory name. Otherwise, EDT creates the journal in the 
default directory. 


The directory that is to contain the journal should not be write-protected. 


To prevent EDT from keeping a record of your editing session, use the 
/NOJOURNAL qualifier in the EDT command line as follows: 


$ EDIT/EDT/NOJOURNAL MEMO.DAT 


Once you have created a journal, enter the EDT/RECOVER command to execute 
the commands in the journal. The asterisk (*) and the percent sign (%) wildcard 
characters are not allowed in the file specification. 


EDIT/EDT 


/OUTPUT=output-file 

/INOOUTPUT 

Determines whether EDT creates an output file at the end of your editing session. 
The default file specification for both the input file and the output file is the same. 
Use the /OUTPUT qualifier to give the output file a different file specification 
from the input file. 


The following command line invokes EDT to edit a file named MEMO.DAT and 
gives the resulting output file the name OUTMEM.DAT: 


$ EDIT/EDT/OUTPUT=OUTMEM.DAT MEMO.DAT 


You can include directory information as part of your output file specification to 
send output to another directory as follows: 


$ EDIT/EDT/OUTPUT=[BARRETT.MAIL]MEMO.DAT MEMO.DAT 


The /NOOUTPUT qualifier suppresses the creation of an output file, but not the 
creation of a journal. If you decide that you do not want an output file, you can 
use the /NOOUTPUT qualifier as follows: 


$ EDIT/EDT/NOOUTPUT MEMO.DAT 


A system interruption does not prevent you from re-creating your editing session 
because a journal is still being maintained. To save your editing session, even 
when you specify /NOOUTPUT, use the line mode command WRITE to put the 
text in an external file before you end the session. 


The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


/READ_ONLY 

/NOREAD_ONLY (default) 

Determines whether EDT keeps a journal and creates an output file. With 
the /NOREAD_ONLY qualifier, EDT maintains the journal and creates an 
output file when it processes the line mode command EXIT. Using the /READ_ 
ONLY qualifier has the same effect as specifying both the /NOJOURNAL and 
/NOOUTPUT qualifiers. 


The following command line invokes EDT to edit a file named CALENDAR.DAT, 
but does not create a journal or an output file: 


$ EDIT/EDT/READ ONLY CALENDAR. DAT 


Use the /READ_ONLY qualifier when you are searching a file and do not intend 
to make any changes to it. To modify the file, use the line mode command WRITE 
to save your changes. Remember, however, that you have no journal. 


/RECOVER 
/JNORECOVER (default) 
Determines whether EDT reads a journal at the start of the editing session. 


When you use the /RECOVER qualifier, EDT reads the appropriate journal and 
processes whatever commands it contains. The appropriate syntax is as follows: 


$ EDIT/EDT/RECOVER MEMO.DAT 


If the journal file type is not .JOU or the file name is not the same as the input 
file name, you must include both the /JOURNAL qualifier and the /RECOVER 
qualifier as follows: . 


$ EDIT/EDT/RECOVER/JOURNAL=SAVE.XXX MEMO.DAT 
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-EDIT/EDT 


Because the /NORECOVER qualifier is the default for EDT, you do not need to 
specify it in a command line. 


Examples 


1. $ EDIT/EDT/OUTPUT=NEWFILE.TXT OLDFILE.TXT 
1 This is the first line of the file OLDFILE.TXT. 
* 


This command invokes EDT to edit the file OLDFILE.TXT. EDT looks for the 
EDTSYS logical name assignment. If EDTSYS is not defined, EDT processes 
the systemwide startup command file SYS$LIBRARY:EDTSYS.EDT. If this 
file does not exist, EDT looks for the EDTINI logical name assignment. If 
EDTINI is not defined, EDT looks for the file named EDTINI.EDT in your 
default directory. If none of these files exists, EDT begins your editing session 
in the default state. When the session ends, the edited file has the name 
NEWFILE.TXT. 


2. $ EDIT/EDT/RECOVER OLDFILE.TXT 


This command invokes EDT to recover from an abnormal] exit during a 
previous editing session. EDT opens the file OLDFILE.TXT, and then 
processes the journal OLDFILE.JOU. Once the journal has been processed, 
the user can resume interactive editing. 
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EDIT/FDL 


EDIT/FDL 


Invokes the Edit/FDL (File Definition Language) utility, which creates and 
modifies FDL files. The /FDL qualifier is required. For a complete description 
of the File Definition Language utility, see the OpenVMS Record Management 
Utilities Reference Manual. 


Format 
EDIT/FDL filespec 
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EDIT/SUM 


EDIT/SUM 
Invokes the SUMSLP utility, a batch-oriented editor, to update a single input file 
with multiple files of edit commands. 
For a complete description of the SUMSLP utility, see the OpenVMS SUMSLP 
Utility Manual. 

Format 


EDIT/SUM _ input-file 
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EDIT/TECO 


EDIT/TECO 


Format 


Parameter 


Description 


Qualifiers 


Invokes the TECO interactive text editor. 


EDIT/TECO [filespec] 
EDIT/TECO/EXECUTE=commanc-file [argument] 


filespec 

Specifies the file to be created or edited using the TECO editor. If the file does 
not exist, it is created by TECO, unless you specify the /(NOCREATE qualifier. 
The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


If you specify the (MEMORY qualifier (default) without a file specification, TECO 
edits the file identified by the logical name TEC$MEMORY. If TECSMEMORY 
has no equivalence string, or if the /NOMEMORY qualifier is specified, TECO 
starts in command mode and does not edit an existing file. 


If you specify the (MEMORY qualifier and a file specification, the file specification 
is equated to the logical name TEC$MEMORY. 


argument 
See the /EXECUTE qualifier. 


The TECO editor creates or edits text files. For detailed information on the use 
of TECO, see the PDP-11 TECO Editor Reference Manual. 


/COMMAND[=filespec] 

/NOCOMMAND 

Controls whether a startup command file is used. The (COMMAND file qualifier 
may be followed by an equal sign (=) and the specification of the command file. 
The default file type for command files is .TEC. 


The following command line invokes TECO to edit a file named MEMO.DAT and 
specifies that TECO use a startup command file named XTECOINI.TEC: 


$ EDIT/TECO/COMMAND=XTECOINI.TEC MEMO.DAT 


If you do not include the /COMMAND qualifier, or if you enter /COMMAND 
without specifying a command file, TECO looks for the TEC$INIT logical name 
assignment. If TEC$INIT is not defined, no startup commands are executed. 


The logical name TEC$INIT can equate either to a string of TECO commands or 
to a dollar sign ($) followed by a file specification. If TEC$INIT translates to a 
string of TECO commands, the string is executed; if it translates to a dollar sign 
followed by a file specification, the contents of the file are executed as a TECO 
command string. For further information, see the PDP-11 TECO Editor Reference 
Manual. 
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EDIT/TECO 
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To prevent TECO from using any startup command file, use the /(NOCOMMAND 
qualifier as follows: 


$ EDIT/TECO/NOCOMMAND MEMO. DAT 


The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


/CREATE (default) 

/NOCREATE 

Creates a new file when the specified input file cannot be found. If the /MEMORY 
qualifier is specified and no input file is specified, the file created is the one 
specified by the logical name TEC$MEMORY. Normally, TECO creates a new file 
to match the input file specification if it cannot find the requested file name in 
the specified directory. When you use the /NOCREATE qualifier in the TECO 
command line and type a specification for a file that does not exist, TECO 
displays an error message and returns you to the DCL command level. The 
/CREATE and /NOCREATE qualifiers are incompatible with the /EXECUTE 
qualifier. 


/EXECUTE=commanc-file [argument] 

Invokes TECO and executes the TECO macro found in the command file. The 
argument, if specified, appears in the text buffer when macro execution starts. 
Blanks or special characters must be enclosed in quotation marks (“”). For 
detailed information on the use of TECO macros, see the PDP-11 TECO Editor 
Reference Manual. 


The /EXECUTE qualifier is incompatible with the /CREATE and /MEMORY 
qualifiers. 


/MEMORY (default) 

/NOMEMORY 

Specifies that the last file you edited with TECO, identified by the logical name 
TECS$MEMORY, will be the file edited if you omit the file specification to the 
EDIT/TECO command. 


/OUTPUT=output-file 

/NOOUTPUT (default) 

Controls how the output file is named at the end of your editing session. By 
default, the output file has the same name as the input file but is given the next 
higher available version number. Use the /OUTPUT qualifier to give the output 
file a file specification different from the input file. 


The following command line invokes TECO to edit a file named MEMO.DAT and 
gives the resulting output file the name OUTMEM.DAT: 


$ EDIT/TECO/OUTPUT=OUTMEM.DAT MEMO.DAT 


You can include directory information as part of your output file specification to 
send output to another directory as follows: 


$ EDIT/TECO/OUTPUT=[BARRRET.MAIL]MEMO.DAT MEMO.DAT 


The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


EDIT/TECO 


/READ_ONLY 

/NOREAD_ONLY (default) 

Controls whether an output file is created. By default, an output file is created; 
the /READ_ONLY qualifier suppresses the creation of the output file. 


Examples 


1. $ EDIT/TECO/OUTPUT=NEWFILE.TXT OLDFILE.TXT 


This EDIT command invokes the TECO editor to edit the file OLDFILE.TXT. 
TECO looks for the TEC$INIT logical name assignment. If TEC$INIT is 
not defined, TECO begins the editing session without using a command file. 
When the session ends, the edited file has the name NEWFILE.TXT. 


2. $ EDIT/TECO/EXECUTE=FIND DUPS "TEMP, ARGS, BLANK" 


In this example, the /EXECUTE qualifier causes the TECO macro contained 
in the file FIND_DUPS.TEC to be executed, with the argument string “TEMP, 
ARGS, BLANK” located in the text buffer. 
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EDIT/TPU 


EDIT/TPU 


Format 
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Invokes the DEC Text Processing utility (DECTPU). By default, this runs the 
Extensible Versatile Editor (EVE). DECTPU provides a structured programming 
language and other components for creating text editors and other applications. 
EVE is a general-purpose text editor that is the OpenVMS default editor. 


For information about editing with EVE, see the OpenVMS User’s Manual and 
online help. 


EDIT[/TPU] _ [input-file] 


ENABLE AUTOSTART 


ENABLE AUTOSTART | 


Format 


Parameters 


Description 


Qualifiers 


Enables the autostart feature on a node for all autostart queues managed by the 
specified queue manager. By default, this command uses the /QUEUES qualifier. 


Requires OPER (operator) privileges. 


For more information on autostart queues, see the chapter on batch and print 
queues in the OpenVMS System Manager’s Manual. 


ENABLE AUTOSTART([/QUEUES] 


None. 


Enabling autostart for queues notifies the queue manager to automatically start 
all of its stopped active autostart queues on a node. It also notifies the queue 
manager to automatically start any of its autostart queues that fail over to the 
node. By default, the ENABLE AUTOSTART command affects the node from 
which it is entered. Specify the /ON_NODE qualifier to enable autostart on a 
different node. 


By default, the command affects autostart queues managed by the default 
queue manager, SYS$QUEUE_MANAGER. Specify the /NAME_OF_MANAGER 
qualifier to disable autostart of a different queue manager’s autostart queues on 
the node. 


An autostart queue is active if it has been activated by the /START qualifier 
with the INITIALIZE/QUEUE command or by the START/QUEUE command 
and has not been stopped by the STOP/QUEUE/NEXT or STOP/QUEUE/RESET 


command. 


When a node boots, autostart is disabled until you enter the ENABLE 
AUTOSTART command. Typically, you would add this command to your site- 
specific startup command procedure or your queue startup command procedure to 
start a node’s autostart queues each time the node boots. 


/NAME_OF_MANAGER=name 

Specifies the name of the queue manager controlling the autostart queues you 
want to enable. The qualifier allows the autostart feature to be used differently 
for different sets of queues. 


If the /NAME_OF_MANAGER qualifier is omitted, the default queue manager 
name SYS$QUEUE_MANAGER is used. 


For more information on multiple queue managers, see the chapter on the queue 
manager in the OpenVMS System Manager’s Manual. 


/ON_NODE=nodename 
Specifies a node in a VMScluster system. Use this qualifier to enable autostart 
on a node other than the one from which you enter the command. 
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ENABLE AUTOSTART 


Examples 
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/QUEUES 
Specifies that autostart is to be enabled for queues. (This qualifier is used by 
default.) 


I, 


2. 


$ INITIALIZE/QUEUE/BATCH/START- 
_$ /AUTOSTART ON=SATURN:: BATCH 1 
$ ENABLE AUTOSTART/QUEUES 


$ DISABLE AUTOSTART/QUEUES 


In this example, the INITIALIZE/QUEUE command creates an autostart 
queue BATCH_1, capable of running on node SATURN. The /START qualifier 
activates the queue for autostart. The ENABLE/AUTOSTART/QUEUES 
command (executed on node SATURN) enables autostart on the node, causing 
the queue (and any other active autostart queues on the node) to begin 
executing jobs. 


The DISABLE AUTOSTART command (executed on node SATURN) stops 
autostart queues on the node and prevents any queues from failing over to 
the node. 


These commands only affect queues managed by the default queue manager 
SYS$QUEUE_MANAGER because the /NAME_OF_MANAGER qualifier is 
not specified. 


Because BATCH_1 is set up to run only on one node, the queue cannot fail 
over to another node and therefore is stopped. However, the queue remains 
active for autostart and will be started when the ENABLE AUTOSTART 
command is entered for node SATURN. No START/QUEUE command is 
needed to restart BATCH_1 unless autostart of the queue is deactivated with 
the STOP/QUEUE/NEXT or STOP/QUEUE/RESET command. 


$ INITIALIZE/QUEUE/BATCH/START- 

_$ /AUTOSTART ON=(NEPTUN::,SATURN::) BATCH 1 
$ ENABLE AUTOSTART/QUEUES/ON_NODE=NEPTUN 

$ ENABLE AUTOSTART/QUEUES/ON NODE=SATURN 


$ STOP/QUEUES/ON_NODE=NEPTUN 


In this example, the INITIALIZE/QUEUE command creates an autostart 
queue BATCH_1. The /START qualifier activates the queue for autostart. 


The first ENABLE AUTOSTART/QUEUES command causes the queue to 
begin executing on node NEPTUN. The second ENABLE AUTOSTART 
/QUEUES command enables autostart on node SATURN to start all stopped 
active autostart queues on that node and to start any autostart queues that 
might fail over to that node. 


Later, suppose node NEPTUN must be removed from the VMScluster 
system. The STOP/QUEUES/ON_NODE command stops all queues on node 
NEPTUN, and causes the autostart queue BATCH_1 to fail over to node 


SATURN. Because the queue is active for autostart, and because autostart 
C ; ; 


ENABLE AUTOSTART 


has been enabled on node SATURN, the queue is automatically started on 
that node. 


This command only affects queues managed by the default queue manager 
SYS$QUEUE_MANAGER because the /NAME_OF_ MANAGER qualifier is 
not specified. 
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ENDSUBROUTINE 


ENDSUBROUTINE 


Defines the end of a subroutine in a command procedure. For more information 
about the ENDSUBROUTINE command, refer to the description of the CALL 
command. 


Format 
ENDSUBROUTINE 
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EOD 


Format 


Parameters 


Description 


Examples 


EOD 


Signals the end of a data stream when a command or program is reading data 
from an input device other than an interactive terminal. 


$ EOD 


None. 


The EOD (end of deck) command in a command procedure or in a batch job does 
the following: 


Terminates input data lines that begin with dollar signs ($). The DECK 
command indicates that the following lines begin with dollar signs and should 
be interpreted as data, not as commands; the EOD command indicates the 
end of the data lines. 


Terminates an input file if multiple input files are contained in the command 
stream without intervening commands. The program or command reading 
the data receives an end-of-file (EOF) condition when the EOD command is 
read. 


The EOD command must be preceded by a dollar sign; the dollar sign must be in 
the first character position (column 1) of the input record. 


1. 


$ CREATE WEATHER.COM 
$ DECK 

$ FORTRAN WEATHER 

$ LINK WEATHER 

$ RUN WEATHER 

$ EOD 

$ @WEATHER 


In this example, the command procedure creates a command procedure called 
WEATHER.COM. The lines delimited by the DECK and EOD commands are 
written to the file WEATHER.COM. Then the command procedure executes 
WEATHER.COM. 


DCLI-211 


EOD 












$ PRINT TESTDATA.OUT 
..9econd Input Data File.. 





...First Input Data File... 
$ RUN MYPROG 
$ PASSWORD HENRY 
$ JOB HIGGINS 






ZK-0785-GE 


The program MYPROG requires two input files; these are read from the 
logical device SYS$INPUT. The EOD command signals the end of the first 
data file and the beginning of the second. The next line that begins with a 


dollar sign (a PRINT command in this example) signals the end of the second 
data file. 
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EOJ 


EOJ 
Marks the end of a batch job submitted through a card reader. 

Format 
$ EOUJ 

Parameters 
None. 

Description 
The EOJ (end of job) command marks the end of a batch job submitted through a 
card reader. An EOJ card is not required; however, if present, the first nonblank 
character in the command line must be a dollar sign ($). If issued in any other 
context, the EOJ command logs the process out. The EOJ command cannot be 
abbreviated. 
The EOF card is equivalent to the EOJ card. 

Example 








...<Ccommand Input Stream... 


$ PASSWORD HENRY 
$ JOB HIGGINS 


ZK-0786-GE 


The JOB and PASSWORD commands mark the beginning of a batch job 
submitted through the card reader; the EOJ command marks the end of the 
job. . 
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EXAMINE 


EXAMINE 


Format 


Parameter 


Description 
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Displays the contents of virtual memory. 


Requires user-mode read (R) access to the virtual memory location 
whose contents you want to examine. 


EXAMINE __location{[:location] 


location[:location] 

Specifies a virtual address or a range of virtual addresses (where the second 
address is larger than the first) whose contents you want to examine. If you 
specify a range of addresses, separate the beginning and ending addresses with a 
colon (:). 


A location can be any valid arithmetic expression containing arithmetic or logical 
operators or previously assigned symbols. Radix qualifiers determine the radix in 
which the address is interpreted; hexadecimal is the initial default radix. Symbol 
names are always interpreted in the radix in which they were defined. The radix 
operators %X, %D, or %O can precede the location. A hexadecimal value must 
begin with a number (or be preceded by %X). 


The DEPOSIT and EXAMINE commands maintain a pointer to the current 
memory location. The EXAMINE command sets this pointer to the last location 
examined when you specify an EXAMINE command. You can refer to this 
location using the period (.) in a subsequent EXAMINE command or DEPOSIT 
command. . 


The EXAMINE command displays the contents of virtual memory. The address 
is displayed in hexadecimal format and the contents are displayed in the radix 
requested, as follows: 


address: contents 


If the address specified is not accessible to user mode, four asterisks (*) are 
displayed in the contents field. 


Radix Qualifiers: The radix default for a DEPOSIT command or an EXAMINE 
command determines how the command interprets numeric literals. The initial 
default radix is hexadecimal; all numeric literals in the command line are 
assumed to be hexadecimal values. If a radix qualifier modifies an EXAMINE 
command, that radix becomes the default for subsequent EXAMINE and 
DEPOSIT commands, until another qualifier overrides it. For example: 


$ EXAMINE/DECIMAL 900 
00000384: 0554389621 


The EXAMINE command interprets the location 900 as a decimal number and 
displays the contents of that location in decimal. All subsequent DEPOSIT and 
EXAMINE commands assume that numbers you enter for addresses and data are 
decimal. Note that the EXAMINE command always displays the address location 
in hexadecimal format. 


Qualifiers 


EXAMINE 


Symbol names defined by = (assignment statement) commands are always 
interpreted in the radix in which they were defined. 


Note that hexadecimal values entered as examine locations or as data to be 
deposited must begin with a numeric character (0 to 9). Otherwise, the command 
interpreter assumes that you have entered a symbol name, and attempts symbol 
substitution. 


You can use the radix operators %X, %D, or %O to override the current default 
when you enter the EXAMINE command. For example: 


$ EXAMINE/DECIMAL %X900 
00000900: 321446536 


-This command requests a decimal display of the data in the location specified as 


hexadecimal 900. 


Length Qualifiers: The initial default length unit for the EXAMINE command 
is a longword. The EXAMINE command displays data, 1 longword at a time, 
with blanks between longwords. If a length qualifier modifies the command, that 
length becomes the default length of a memory location for subsequent EXAMINE 
and DEPOSIT commands, until another qualifier overrides it. 


Restriction on Placement of Qualifiers: The EXAMINE command analyzes 
expressions arithmetically. Therefore, qualifiers are interpreted correctly only 
when they appear immediately after the command name. 


/ASCII 
Displays the data at the specified location in ASCII format. 


Binary values that do not have ASCII equivalents are displayed as periods (. ). 


When you specify the /ASCII qualifier, or when ASCII mode is the default, 
hexadecimal is used as the default radix for numeric literals that are specified on 
the command line. 


/BYTE 
Displays data at the specified location 1 byte at a time. 


/DECIMAL 
Displays the contents of the specified location in decimal format. 


/HEXADECIMAL 
Displays the contents of the specified location in hexadecimal format. 


/LONGWORD 
Displays data at the specified location 1 longword at a time. 


/OCTAL 
Displays the contents of the specified location in octal format. 


/WORD 


- Displays data at the specified location 1 word at a time. 
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EXAMINE 


Examples 
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1. 


$ RUN MYPROG 


$ EXAMINE 2678 


0002678: 1F4C5026 
$ CONTINUE 


In this example, the RUN command begins execution of the image 
MYPROG.EXE. While MYPROG is running, pressing Ctrl/Y interrupts 

its execution, and the EXAMINE command displays the contents of virtual 
memory location 2678 (hexadecimal). 


$ BASE = %X1C00 

$ READBUF = BASE + %X50 

$ ENDBUF = BASE + %XA0 

$ RUN TEST 

[ow 

$ EXAMINE/ASCII READBUF:ENDBUF 

00001C50: BEGINNING OF FILE MAPPED TO GLOBAL SECTION 


In this example, before executing the program TEST.EXE, symbolic names 
are defined for the program’s base address and for labels READBUF and 
ENDBUF; all are expressed in hexadecimal format using the radix operator 
%X. READBUF and ENDBUF define offsets from the program base. 


While the program is executing, pressing Ctrl/Y interrupts it, and the 
EXAMINE command displays in ASCII format all data between the specified 
memory locations. 


EXCHANGE 


EXCHANGE 


Format 


Invokes the Exchange utility (EXCHANGE), which manipulates mass storage 
volumes that are written in formats other than those normally recognized by the 
operating system. 


EXCHANGE allows you to perform any of the following tasks: 
¢ Create foreign volumes. 

e ‘Transfer files to and from the volume. 

e List directories of the volume. 


For block-addressable devices, such as RT—11 disks, EXCHANGE performs 
additional operations such as renaming and deleting files. EXCHANGE can also 
manipulate Files—11 files that are images of foreign volumes; these files are called 
virtual devices. 


For a complete description of EXCHANGE, see the OpenVMS Exchange Utility 
Manual and the online help. 


EXCHANGE  [subcommand] [filespec] [filespec] 
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EXCHANGE/NETWORK 


EXCHANGE/NETWORK 


Format 


Parameters 
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Enables the operating system to transfer files to or from operating systems 
that do not support OpenVMS file organizations. The transfer occurs over a 
DECnet network communications link that connects OpenVMS systems and non 
OpenVMS operating system nodes. 


Using DECnet services, the EXCHANGE/NETWORK command can perform any 
of the following tasks: , 


e Transfer files between an OpenVMS node and a non OpenVMS system node. 
e Transfer a group of input files to a group of output files. 


e Transfer files between two non OpenVMS nodes, provided those nodes share 
DECnet connections with the OpenVMS node that issues the EXCHANGE 
/NETWORK command. 


EXCHANGE/NETWORK _input-filespec[,...] output-filespec 


input-filespec{,...] 

Specifies the name of an existing file to be transferred. The asterisk (*) and the 
percent sign (%) wildcard characters are allowed. If you specify more than one 
file, separate the file specifications with commas (, ). 


output-filespec 
Specifies the name of the output file into which the input is transferred. 


You must specify at least one field in the output file specification. If you omit 
the device or directory, your current default device and directory are used. The 
EXCHANGE/NETWORK command replaces any other missing fields (file name, 
file type, and version number) with the corresponding field of the input file 
specification. 


The EXCHANGE/NETWORK command creates a new output file for every input 
file that you specify. 


You can use the asterisk (*) wildcard character in place of the file name, the file 
type, or the version number. The EXCHANGE/NETWORK command uses the 
corresponding field in the related input file to name the output file. You can also 
use the asterisk (*) wildcard character in the output file specification to direct 
EXCHANGE/NETWORK to create more than one output file. For example: 


$ EXCHANGE/NETWORK A.A,B.B MYPC::*.C 


This EXCHANGE/NETWORK command creates the files A.C and B.C at the non 
OpenVMS target node MYPC. 


A more complete explanation of the asterisk (*) and the percent sign (% ) 
wildcard characters and version numbers follows in the Description section. 


Description 


EXCHANGE/NETWORK 


The EXCHANGE/NETWORK command imposes the following restrictions: 


¢ Transfers of files can occur only between disk devices. (If a disk device is not 
the desired permanent residence for the file, you must either move the file to 
a disk before issuing the command or retrieve the file from a disk after the 
command completes.) 


¢ The remote system must have a block size of 512 bytes, where a byte is 8 bits 
long. 


e The nodes transferring files must support the DECnet Data Access Protocol 
(DAP). 


The OpenVMS Record Management Services (RMS) facility provides the operating 
system access to records in OpenVMS RMS files. To transfer OpenVMS RMS files 
between two nodes where both nodes are OpenVMS nodes, use one of the other 
DCL commands (such as COPY, APPEND, or CONVERT), as appropriate. These 
commands recognize RMS file organizations and are designed to ensure that RMS 
record structures are preserved as your files are moved. 


Use the EXCHANGE/NETWORK command to transfer files between OpenVMS 
nodes and non OpenVMS nodes when the differences in the file organizations 
would otherwise prevent the transfer or could lead to undesirable results. While 
using the COPY command ensures that both the contents and the attributes of 
a replicated file are preserved, the EXCHANGE/NETWORK command has more 
advantages. The EXCHANGE/NETWORK command offers you explicit control of 
your record attributes during file transfers, with the opportunity to make. a file 
usable on several different operating systems. 


The EXCHANGE/NETWORK command transfers files between OpenVMS nodes 
and non OpenVMS nodes connected to the same DECnet network. If the non 
OpenVMS system does not support OpenVMS file organizations, the EXCHANGE 
/NETWORK command can modify or discard file and record attributes during 
the transfer. However, if the target system is an OpenVMS node, you have the 
option of applying new file and record attributes to the output file by supplying 
a File Definition Language (FDL) file, as described later in this section. The 
EXCHANGE/NETWORK command provides a number of defaults to handle the 
majority of transfers properly. However, in some situations, you need to know 
your file or record format requirements at both nodes. 


OpenVMS File and Record Attributes 


All RMS files in the OpenVMS environment include stored information, known 
as the file and record attributes, to describe the file and record characteristics. 
File attributes consist of items such as file organization, file protection, and 

file allocation information. Record attributes consist of items such as the 
record format, record size, key definitions for indexed files, and carriage control 
information. These attributes define the data format and access methods for the 
OpenVMS RMS facility. 


NonOpenVMS operating systems that do not support OpenVMS file organizations 
have no means of storing file and record attributes with their files. Transferring 
an OpenVMS file to a non OpenVMS system that is unable to store and handle 
file and record attributes can result in most of this information being discarded. 
Removing these attributes from a file can render it useless if it must be returned 
to the OpenVMS system. 
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Transferring Files to OpenVMS Nodes 


When you transfer files to an OpenVMS system from a non OpenVMS system, the 
files typically assume default file and record attributes. However, you can specify 
the attributes that you want the file to acquire in a File Definition Language 
(FDL) file. Alternatively, if transferring a CDA document, enter the following 
command after the EXCHANGE/NETWORK command: 


$ SET FILE/SEMANTICS=[ddif,dtif] document-name.doc 


If you specify an FDL file with the /FDL qualifier, the FDL file determines the 
characteristics of the output file. This feature is useful in establishing compatible 
file and record attributes when you transfer a file from a non OpenVMS system 
to an OpenVMS system. However, when you use an FDL file, you also assume 
responsibility for determining the required characteristics. 


For more information on FDL files, see the OpenVMS Record Management 
Utilities Reference Manual. 


Transferring Files to Non-OpenVMS Nodes 


The EXCHANGE/NETWORK command discards file and record attributes 
associated with an OpenVMS file during a transfer to a non OpenVMS system 
that does not support OpenVMS file organizations. Be aware that the loss of file 
and record attributes in the transfer can render the output on useless for many 
applications. 


Selecting Transfer Modes 


The EXCHANGE/NETWORK command has four transfer mode options: 
AUTOMATIC, BLOCK, RECORD, and CONVERT. For most file transfers, 
AUTOMATIC is sufficient. The AUTOMATIC transfer mode option allows the 
EXCHANGE/NETWORK command to transfer files using either block or record 
I/O. The selection is based on the input file organization and the operating 
systems involved. 


Selecting the BLOCK transfer mode option forces the EXCHANGE/NETWORK 
command to open both the input and output files for block I/O access. The input 
file is then transferred to the output file block by block. Use this transfer mode 
when you transfer executable images. It is also useful when you must preserve 
a file’s content exactly, which is a common requirement when you store files 
temporarily on another system or when cooperating applications exist on the 
systems. 


Selecting the RECORD transfer mode option forces the EXCHANGE/NETWORK 
command to open both the input file and output file for record I/O access. The 
input file is then transferred to the output file record by record. This transfer 
mode is primarily used for transferring text files. 


Selecting the CONVERT transfer mode option forces the EXCHANGE/NETWORK 
command to open the input file for RECORD access and the output file for 
BLOCK access. Records are then read: in from the input file, packed into blocks, 
and are written to the output file. This transfer mode is primarily used for 
transferring files with no implied carriage control. For example, to transfer a 

file created with DIGITAL Standard Runoff (DSR) to a DECnet DOS system, you 


- must use the CONVERT transfer mode option. To transfer the resultant output 


file back to an OpenVMS node, use the AUTOMATIC transfer mode option. 


EXCHANGE/NETWORK 


Wildcard Characters 

The asterisk (*) and the percent sign (%) wildcard characters are permitted in 
the file specifications and follow the behavior typical of other OpenVMS system 
commands with respect to the OpenVMS node. 


When more than one input file is specified, but the asterisk (*) or the percent 
sign (%) wildcard characters are not specified in the output file specification, 
the first input file is copied to the output file, and each subsequent input file is 
transferred and given a higher version number of the same output file name. 
Note that the files are not concatenated into a single output file. Also note that 
when you transfer files to foreign systems that do not support version numbers, 
only one output file results, and it is the last input file. 


To create multiple output files, specify multiple input files and use at least one of 
the following: 


e An asterisk (*) wildcard character in the output file name, file type, or 
version number field 


e Only a node name, a device name, or a directory specification as the output 
file specification . 


When you create multiple output files, the EXCHANGE/NETWORK command 
uses the corresponding field from each input file in the output file name. 


Use the /LOG qualifier when you specify multiple input and output files to verify 
that the files were copied as you intended. 


Version Numbers 


The following guidelines apply when the target node file formats accept version 
numbers. 


If no version numbers are specified for input and output files, the EXCHANGE 
/NETWORK command (by default) assigns a version number to the output files 
that is either of the following: 


e The version number of the input file 


e A version number one greater than the highest version number of an existing 
file with the same file name and file type 


When the output file version number is specified by an asterisk (*) wildcard 
character, the EXCHANGE/NETWORK command uses the version numbers of 
the associated input files as the version numbers of the output files. 


If the output file specification has an explicit version number, the EXCHANGE 
/NETWORK command normally uses that number for the output file specification. 
However, if an equal or higher version of the output file already exists, no 
warning message is issued, the file is copied, and the version number is set 

to a value one greater than the highest version number already existing. 


File Protection and Creation/Revision Dates 

The EXCHANGE/NETWORK command treats an output file as a new file when 
any portion of the output file name is specified explicitly. When the output node 
is an OpenVMS system, the creation date for a new file is set to the current time 
and date. However, if the output file specification consists only of the asterisk (* ) 
and the percent sign (% ) wildcard characters, the output file no longer qualifies 
as a new file, and, therefore, the creation date of the input file is used. That is, if 
the output file specification is one of the following, the creation date becomes that 
of the input file: *, *.*, or *.*;*. 
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The revision date of the output file is always set to the current time and date; 
the backup date is set to zero. The output file is assigned a new expiration date. 
(Expiration dates are set by the file system if retention is enabled; otherwise, they 
are set to zero.) 


When the target node is an OpenVMS node, the protection and access control 
list (ACL) of the output file is determined by the following parameters, in the 
following order: 


1. Protection of previously existing versions of the output file 


’ 2. Default protection and ACL of the output directory 


3. Process default file protection 
For an introduction to ACLs, see the OpenVMS Guide to System Security. 


On OpenVMS systems, the owner of the output file usually is the same as the 
creator of the output file. However, if a user with extended privileges creates the 
output file, the owner is either the owner of the parent directory or the owner of 
a previous version of the output file, if one exists. 


Extended privileges include any of the following: 
e SYSPRV (system privilege) or BYPASS 
e System user identification code (UIC) 


¢ GRPPRV (group privilege) if the owner of the parent directory (or previous 
version of the output file) is in the same group as the creator of the new 
output file 


e An identifier (with the resource attribute) representing the owner of the 
parent directory (or previous version of the output file) 


/BACKUP 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /BACKUP qualifier selects files according to the dates of their most recent 
backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you do not specify any of these four time qualifiers, the default is 
the /CREATED qualifier. 


/BEFORE[=time] 

Selects only those files dated prior to the specified time. You can specify time 
as absolute time, as a combination of absolute and delta times, or as one of 

the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier 
to indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


/BY_OWNER[=uic] 
Selects only those files whose owner user identification code (UIC) matches the 
specified owner UIC. The default UIC is that of the current process. 


Specify the UIC by using standard UIC format as described in the OpenVMS 
Guide to System Security. 
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/CONFIRM 

/NOCONFIRM (default) 

Controls whether a request is issued before each file transfer operation to confirm 
that the operation should be performed on that file. The following responses are 
valid: 


YES NO QUIT 
TRUE FALSE Ctrl/Z 
1 0 ALL 


You can use any combination of uppercase and lowercase letters for word 
responses. Word responses can be abbreviated to one or more letters (for example, 
T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative 
answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, 

and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that 
you want to stop processing the command at that point. When you respond by 
entering ALL, the command continues to process, but no further prompts are 
given. If you type a response other than one of those in the list, DCL issues an 
error message and redisplays the prompt. ; 


/CREATED (default) 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The 
/CREATED qualifier selects files based on their dates of creation. This qualifier is 
incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which 
also allow you to select files according to time attributes. If you do not specify 
any of these four time qualifiers, the default is the (CREATED qualifier. 


/EXCLUDE=(filespecf,...]) 

Excludes the specified files from the file transfer operation. You can include 

a directory but not a device in the file specification. The asterisk (*) and 

the percent sign (% ) wildcard characters are allowed in the file specification. 
However, you cannot use relative version numbers to exclude a specific version. If 
you specify only one file, you can omit the parentheses. 


/EXPIRED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. 
The /EXPIRED qualifier selects files according to their expiration dates. (The 
expiration date is set with the SET FILE/EXPIRATION_DATE command.) 
The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and 
/MODIFIED qualifiers, which also allow you to select files according to time 
attributes. If you do not specify any of these four time qualifiers, the default is 
the /CREATED qualifier. 


/FDL=fdl-filespec 

Specifies that the output file characteristics are described in the File Definition 
Language (FDL) file. Use this qualifier when you require special output file 
characteristics. For more information about FDL files, see the OpenVMS Record 
Management Utilities Reference Manual. 


Use of the /FDL qualifier implies that the transfer mode is block by block. 
However, the transfer mode you specify with the /TRANSFER_MODE qualifier 
prevails. 
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/LOG 

/NOLOG (default) 

Controls whether the EXCHANGE/NETWORK command displays the file 
specifications of each file copied. 


When you use the /LOG qualifier, the EXCHANGE/NETWORK command displays 
the following for each copy operation: 


¢ The file specifications of the input and output files 


¢ The number of blocks or the number of records copied (depending on whether 
the file is copied on a block-by-block or record-by-record basis) 


/MODIFIED 

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The 
/MODIFIED qualifier selects files according to the date on which they were last 
modified. This time qualifier is incompatible with the /BACKUP, /CREATED, 
and /EXPIRED qualifiers, which also allow you to select files according to time 
attributes. If you do not specify any of these four time qualifiers, the default is 
the /CREATED qualifier. 


/SINCE[=time] 

Selects only those files dated after the specified time. You can specify time 

as absolute time, as a combination of absolute and delta times, or as one of 
the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following time qualifiers with the /SINCE 

qualifier to indicate the time attribute to be used as the basis for selection: 
/BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED. 


For complete information about specifying time values, see the OpenVMS User’s 
Manual. 


/TRANSFER_MODE=option 
Specifies the I/O method to be used in the transfer. This qualifier is useful for all 
file formats. You can specify any one of the following options: 


Option Function 


AUTOMATIC Allows the EXCHANGE/NETWORK 
command to determine the appropriate 
transfer mode. This is the default transfer 


mode. 

BLOCK Opens both the input and output files for 
block I/O and transfers the files block by 
block. 

CONVERT[=optionf,...]] Reads records from the input file, packs 


them into blocks, and writes them to the 
output file in block mode. The options 
listed in the following table determine what 
additional information is inserted during the 
transfer. 
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Option 
RECORD 


EXCHANGE/NETWORK 


Function 


Opens both the input and output files for 
record J/O and transfers the files record by 
record. The target system must support 
record operations, and the input file must be 
record oriented. 


The following four options are available with the CONVERT transfer mode to 
control the insertion of special characters in the records: 


Option 
CARRIAGE_CONTROL 


COUNTED 


FIXED_CONTROL 


RECORD_SEPARATOR= 


separator 


Function 


Any carriage control information in the 
input file is interpreted, is expanded into 
actual characters, and is included with each 
record. 


The length of each record, in bytes, is 
included at the beginning of the record. 
The length includes all FIXED_CONTROL, 
CARRIAGE_CONTROL, and RECORD_ 
SEPARATOR information in each record. 


All variable length with fixed control record 
(VFC) information is written to the output 
file as part of the data. This information 
follows the record length information, if the 
COUNTED option was specified. 

A 1- or 2-byte record separator is inserted 
between each record. Record separator 
characters are the last characters in the 
record. The three choices for separator 
characters are as follows: 


¢ CR: Specifies carriage return only. 


e LF: Specifies line feed only. 


© CRLF: Specifies carriage return and line 


feed. 


1. $ EXCHANGE/NETWORK VMS FILE.DAT KUDOS::FOREIGN SYS.DAT 


In this example, the EXCHANGE/NETWORK command transfers the file 
VMS_FILE.DAT located in the current default device and directory to the 

file FOREIGN_SYS.DAT on the non OpenVMS node KUDOS. Because the 
/TRANSFER_MODE qualifier was not explicitly specified, the EXCHANGE 
/NETWORK command automatically determines whether the transfer method 


should be block or record I/O. 


DCLI-225 


EXCHANGE/NETWORK 


DCLI-226 


2. 


$ EXCHANGE/NETWORK/TRANSFER_MODE=BLOCK - 
_$ KUDOS: :FOREIGN SYS.DAT VMS FILE.DAT 


In this example, the EXCHANGE/NETWORK command transfers the file 
FOREIGN_SYS.DAT from the non OpenVMS node KUDOS to the file VMS_ 
FILE.DAT in the current default device and directory. Block I/O is specified 
for the transfer mode. 


$ EXCHANGE/NETWORK/FDL=VMS FILE DEFINITION.FDL - 
_$ KUDOS::REMOTE FILE.TXT VMS FILE.DAT 


In this example, the EXCHANGE/NETWORK command transfers the file 
REMOTE_FILE.TXT on node KUDOS to the file VMS_FILE.DAT. The 

file attributes for the output file VMS_FILE.DAT are obtained from the 

File Definition Language (FDL) source file VMS_FILE_DEFINITION.FDL. 
For more information about creating FDL files, see the OpenVMS Record 
Management Utilities Reference Manual. Because the qualifier /FDL is 
specified and the /TRANSFER_MODE qualifier is omitted, the transfer mode 
uses block I/O, by default. 


$ EXCHANGE/NETWORK - 

_$ /TRANSFER_MODE=CONVERT=(CARRIAGE CONTROL, COUNTED, - 
$ RECORD_SEPARATOR=CRLF,FIXED CONTROL) - 

_$ PRINT FILE.TXT KUDOS::* 


In this example, the EXCHANGE/NETWORK command transfers the file 
PRINT_FILE.TXT from the current default device and directory to the 

file PRINT_FILE.TXT on the non OpenVMS node KUDOS. The use of the 
CONVERT option with the /TRANSFER_MODE qualifier forces the input file 
to be read in record by record, modified as specified by the CONVERT options 
that follow, and written to the output file block by block. As many records as 


- will fit are packed into the output blocks. 


The CONVERT option CARRIAGE_CONTROL specifies that carriage control 
information is converted to ASCII characters and is inserted before the data 
or is appended to the record, depending on whether prefix control or postfix 
control, or both, are used. The CONVERT option FIXED_CONTROL specifies 
that any fixed control information be translated to ASCII characters and be 
inserted at the beginning of the record. The CONVERT option RECORD_ 


_ SEPARATOR=CRLF appends the two specified characters, carriage return 


and line feed, to the end of the record. The CONVERT option COUNTED 
specifies that the total length of the record must be counted (once the impact 
of all the previous convert options have been added), and the result is to be 
inserted at the beginning of the record, in the first 2 bytes. 


EXIT 


Format 


Parameter 


Description 


EXIT 


Terminates processing of a command procedure or subroutine and returns 
control to the calling command level—either an invoking command procedure 

or interactive DCL. The EXIT command also terminates an image normally after 
a user enters Ctrl/Y (executing another image has the same effect). 


EXIT [status-code] 


status-code 

Defines a numeric value for the reserved global symbol $STATUS. You can specify 
the status-code parameter as an integer or an expression equivalent to an integer 
value. The value can be tested by the next outer command level. The low-order 3 
bits of the value determine the value of the global symbol $SEVERITY. 


If you specify a status code, DCL interprets the code as a condition code. Note 
that even numeric values produce warning, error, and fatal error messages, and 
that odd numeric values produce either no message or a success or informational 
message. 


If you do not specify a status code, the current value of $STATUS is saved. When 
control returns to the outer command level, $STATUS contains the status of the 
most recently executed command or program. 


The EXIT and STOP commands both provide a way to terminate the execution of 
a procedure. The EXIT command terminates execution of the current command 
procedure and returns control to the calling command level. If you enter the 
EXIT command from a noninteractive process (such as a batch job), at command 
level 0, then the process terminates. 


The STOP command returns control to command level 0, regardless of the current 
command level. If you execute the STOP command from a command procedure or 
from a noninteractive process (such as a batch job), the process terminates. 


When a DCL command, user program, or command procedure completes 
execution, the command interpreter saves the condition code value in the 
global symbol $STATUS. If an EXIT command does not explicitly set a value 
for $STATUS, the command interpreter uses the current value of $STATUS to 
determine the error status. 


The low-order 8 bits of the status value contained in $STATUS represent the 
severity of the condition. The reserved global symbol $SEVERITY contains this 
portion of the condition code. Severity values range from 0 to 4, as follows: 


DCLI-227 


EXIT 


Examples 


DCLI-228 


Value Severity 

0 Warning 

1 Success 

2 Error 

3 Information 

4 Severe (fatal) error 


Note that the success and information codes have odd numeric values, and that 
warning and error codes have even numeric values. 


When any command procedure exits and returns control to another level, the 
command interpreter tests the current value of $STATUS. If $STATUS contains 
an even numeric value and if its high-order bit is 0, the command interpreter 
displays the system message associated with that status code, if one exists. (If no 
message exists, the message NOMSG will be displayed.) If the high-order bit is 1, 
the message is not displayed. 


When a command procedure exits following a warning or error condition that has 
already been displayed by a DCL command, the command interpreter sets the 
high-order bit of $STATUS to 1, leaving the remainder of the value intact. This 
ensures that error messages are not displayed by both the command that caused 
the error, and by the command procedure. 


The EXIT command, when used after you interrupt an image with Ctrl/Y, causes 
a normal termination of the image that is currently executing. If the image 
declared any exit-handling routines, they are given control. This is in contrast 
to the STOP command, which does not execute exit-handling routines. For this 
reason, the EXIT command is generally preferable to the STOP command. 


1. $ EXIT 1 


The EXIT command in this example exits to the next higher command level, 
giving $STATUS and $SEVERITY a value of 1. 


2. $ ON WARNING THEN EXIT 
$ FORTRAN ‘Pl’ 
$ LINK ‘Pl’ 
$ RUN ‘Pl’ 


The EXIT command in this example is used as the target of an ON command; 
this statement ensures that the command procedure terminates whenever 
any warnings or errors are issued by any command in the procedure. 


The procedure exits with the status value of the command or program that 
caused the termination. 


EXIT 


$ START: 

$ ' IF (Pl .EQS. "TAPE") .OR. (Pl .EQS. "DISK") THEN GOTO ‘Pl’ 
$ INQUIRE Pl "Enter device (TAPE or DISK)" 

$ GOTO START 

$ TAPE: ! Process tape files’ 

$ EXIT 


$ DISK: ! Process disk files 


$ EXIT 


The command procedure in this example shows how to use the EXIT 
command to terminate different command paths within the procedure. To 
execute the procedure, you must enter either TAPE or DISK as a parameter. 
The IF command uses a logical OR to test whether either of these strings 
was entered. If the result is true, the GOTO command branches to the 
corresponding label. If Pl was neither TAPE nor DISK, the INQUIRE 
command prompts for a correct parameter. 


The commands following each of the labels TAPE and DISK provide different 
paths through the procedure. The EXIT command before the label DISK 
ensures that the commands after the label DISK are executed only if the 
procedure explicitly branches to DISK. 


Note that the EXIT command at the end of the procedure is not required 
because the end of the procedure causes an implicit EXIT command. Use of 
the EXIT command, however, is recommended. 


$ IF Pl. EQS. "" THEN - 

INQUIRE Pl "Enter filespec (null to exit)" 
$ IF Pl .EQS. "" THEN EXIT 
$ PRINT ‘Pl’ /AFTER=20:00/COPIES=50/FORMS=6 


The command procedure in this example tests whether a parameter was 
passed to it; if the parameter was not passed, the procedure prompts 

for the required parameter. Then it retests the parameter P1. If a null 
string, indicated by a carriage return for a line with no data, is entered, the 
procedure exits. Otherwise, it executes the PRINT command with the current 
value of P1 as the input parameter. 


$ IF Pl .EQS. "" THEN INQUIRE Pl "Code" 
$ CODE = %X’P1’ 
$ EXIT CODE 


The command procedure in this example, E.COM, illustrates how to 
determine the system message, if any, associated with a hexadecimal system 
status code. The procedure requires a parameter and prompts if none is 
entered. Then it prefixes the value with the radix operator %X and assigns 
this string to the symbol CODE. Finally, it issues the EXIT command with 
the hexadecimal value. The following example uses the procedure E.COM: 


$ @E 1c 
tSYSTEM-F-EXQUOTA, exceeded quota 


When the procedure exits, the value of $STATUS is %X1C, which equates to 
the EXQUOTA message. Note that you can also use the FSMESSAGE lexical 
function to determine the message that corresponds to a status code. 
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6. $ RUN MYPROG 
$ EXIT 
In this interactive example, the RUN command initiates execution of the 
image MYPROG.EXE. Then pressing Ctrl/Y interrupts the execution. The 
EXIT command that follows calls any exit handlers declared by the image 
before terminating MYPROG.EXE. 


DCLI-230 


FONT 


Format 


FONT 


Converts an ASCII bitmap distribution format (BDF) into binary portable 
compiled format (PCF) on Alpha systems and into binary server natural form 
(SNF) on VAX systems. The DECwindows server uses a PCF or SNF file to 
display a font. In addition to converting the BDF file to binary form, the font 
compiler provides statistical information about the font and the compilation 
process. For more information about using the font compiler, refer to the 
OpenVMS DECwindows programming documentation. 


FONT _ filespec 
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GOSUB 


Format 


_ Parameter 


Description 


Transfers control to a labeled subroutine in a command procedure without 
creating a new procedure level. 


GOSUB label 


label 

Specifies a label of 1 to 255 alphanumeric characters that appears as the first 
item on a command line. A label may not contain embedded blanks. When the 
GOSUB command is executed, control passes to the command following the 
specified label. 


The label can precede or follow the GOSUB statement in the current command 
procedure. When you use a label in a command procedure, it must be terminated 
with a colon (:). If you use duplicate labels, control is always given to the label 
most recently read by DCL. 


Use the GOSUB command in command procedures to transfer control to a 
subroutine specified by the label. If the command stream is not being read from a 
random-access device (that is, a disk device), the GOSUB command performs no 
operation. 


The RETURN command terminates the GOSUB subroutine procedure, returning 
control to the command following the calling GOSUB statement. The RETURN 
command accepts an optional status value. 


The GOSUB command does not cause the creation of a new procedure level. 
Therefore, it is referred to as a “local” subroutine call. Any labels and local 


* symbols defined in the current command procedure level are available to a 
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subroutine invoked with a GOSUB command. The GOSUB command can be 
nested up to a maximum of 16 levels per procedure level. 


When the command interpreter encounters a label, it enters the label in a label 

table. This table is allocated from space available in the local symbol table. If the 
command interpreter encounters a label that already exists in the table, the new 
definition replaces the existing one. Therefore, if you use duplicate labels, control 
is always given to the label most recently read by DCL. The following rules apply: 


e If duplicate labels precede and follow the GOSUB command, control is given 
to the label preceding the command. 


e If duplicate labels all precede the GOSUB command, control is given to the 
most recent label, that is, the one nearest the GOSUB command. 


e If duplicate labels all follow the GOSUB command, control is given to the one 
nearest the GOSUB command. 


If a label does not exist in the current command procedure, the procedure cannot 
continue and is forced to exit. 


Example 


GOSUB 


Note that the amount of space available for labels is limited. If a command 
procedure uses many symbols and contains many labels, the command interpreter 
may run out of table space and issue an error message. 


! 
$! GOSUB.COM 
$! 
$ SHOW TIME 
$ GOSUB TEST1 
$ WRITE SYSSOUTPUT "success completion" 
$ EXIT 
$! 
$! TEST1 GOSUB definition 
$! 
$ TESTI: 
WRITE SYSSOUTPUT "This is GOSUB level 1." 
GOSUB TEST2 
RETURN 3X1 


tT tT In 


$! 
$! TEST2 GOSUB definition 
$! 
$ TEST2: 
WRITE SYSSOUTPUT "This is GOSUB level 2." 
' GOSUB TEST3 
RETURN 


$ 
$ 
$ 
$! 
$! TEST3 GOSUB definition 
! 
; TEST3: 

$ WRITE SYSSOUTPUT "This is GOSUB level 3." 

$ RETURN 

This sample command procedure shows how to use the GOSUB command to 
transfer control to labeled subroutines. The GOSUB command transfers control 
to the subroutine labeled TEST1. The procedure executes the commands in 
subroutine TEST1, branching to the subroutine labeled TEST2. The procedure 
then executes the commands in subroutine TEST2, branching to the subroutine 
labeled TEST3. Each subroutine is terminated by the RETURN command. After 
TESTS is executed, the RETURN command returns control back to the command 
line following each calling GOSUB statement. At this point, the procedure has 
been successfully executed. 
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DCLI-234 


Transfers control to a labeled statement in a command procedure. 
GOTO label 


label 

Specifies a label of 1 to 255 alphanumeric characters that appears as the first 
item on a command line. A label cannot contain embedded blanks. When the 
GOTO command is executed, control passes to the command following the 
specified label. 


When you use a label in a command procedure, it must be terminated with a 
colon (:). If you use duplicate labels, control is always given to the label most 
recently read by DCL. 


Use the GOTO command in command procedures to transfer control to a line 
that is not the next line in the procedure. The label can precede or follow the 
GOTO statement in the current command procedure. If the command stream is 
not being read from a random-access device (that is, a disk device), the GOTO 
command performs no operation. 


If the target label of a GOTO command is inside a separate IF-THEN-ELSE 
construct, an error message (DCL-W-USGOTO) is returned. 


When the command interpreter encounters a label, it enters the label in a label 
table. This table is allocated from space available in the local symbol table. If the 
command interpreter encounters a label that already exists in the table, the new 
definition replaces the existing one. Therefore, if you use duplicate labels, control 
is always given to the label most recently read by DCL. In general: 


e If duplicate labels precede and follow the GOTO command, control is given to 
the label preceding the command. 


e If duplicate labels all precede the GOTO command, control is given to the 
most recent label, that is, the one nearest the GOTO command. 


e If duplicate labels all follow the GOTO command, control is given to the one 
nearest the GOTO command. 


If a label does not exist in the current command procedure, the procedure cannot 
continue and is forced to exit. 


Note that the amount of space available for labels is limited. If a command 
procedure uses many symbols and contains many labels, the command interpreter 
may run out of table space and issue an error message. 


Examples 


1. 


GOTO 


$ IF Pl .EQS. "HELP" THEN GOTO TELL 
$ IF Pl .EQS. "" THEN GOTO TELL 


$ EXIT 

$ TELL: 

$ TYPE SYSSINPUT 

To use this procedure, you must enter a value for Pl. 


$ EXIT 


In this example, the IF command checks the first parameter passed to the 
command procedure; if this parameter is the string HELP or if the parameter 
is not specified, the GOTO command is executed and control is passed to 

the line labeled TELL. Otherwise, the procedure continues executing until 
the EXIT command is encountered. At the label TELL, a TYPE command 
displays data in the input stream that documents how to use the procedure. 


$ ON ERROR THEN GOTO CHECK 


$ EXIT 
$ CHECK: ! Error handling routine 


$ END: 
$ EXIT 


The ON command establishes an error-handling routine. If any command or 
procedure subsequently executed in the command procedure returns an error 
or severe error, the GOTO command transfers control to the label CHECK. 
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The HELP command invokes the HELP Facility to display information about 
use of the system, including formats and explanations of commands, parameters, 
qualifiers and system messages. In response to the Topic? prompt; you can: 


e Type the name of the command or topic for which you need help. 
¢ Type INSTRUCTIONS for more detailed instructions on how to use HELP. 


¢ Type HINTS if you are not sure of the name of the command or topic for 
which you need help. 


¢ Type /MESSAGE for help with the HELP/MESSAGE utility. 
¢ Type a question mark (?) to redisplay the most recently requested text. 
e Press the RETURN key one or more times to exit from HELP. 


You can abbreviate any topic name, although ambiguous abbreviations result in 
all matches being displayed. 


HELP  [topic[subtopic...]] 


topic[subtopic...] 
Specifies the topics or topic and subtopics on which you want information from a 
help library. 


Information within help libraries is arranged in a hierarchical manner. The levels 
are as follows: 


1. None—If you do not specify a keyword, the Help facility describes the HELP 
command and lists the topics that are documented in the root library. Each 
item in the list is a keyword in the first level of the hierarchy. 


2. Topic-name—lIf you specify a keyword by naming a topic, the Help facility 
describes the topic as it is documented in either the root library or in one 
of the other enabled default libraries. Keywords for additional information 
available on this topic are listed. 


3. Topic-name subtopic—If you specify a subtopic following a topic, the oP 
facility provides a description of the specified subtopic. 


4. @filespec followed by any of the previous levels—If you specify a help library 
to replace the current root library, the Help facility searches that library for 
a description of the topic or subtopic specified. The file specification must 
take the same form as the file specification included with the /LIBRARY 
command qualifier. However, if the specified library is an enabled user- 
defined default library, the file specification can be abbreviated to any unique 
leading substring of that default library’s logical name translation. 


Qualifiers 


HELP 


To use the Help facility on OpenVMS in its simplest form, enter the HELP 
command from your terminal. The Help facility displays a list of topics at your 
terminal and the prompt Topic?. To see information on one of the topics, type the 
topic name after the prompt. The system displays information on that topic. 


If the topic has subtopics, the HELP command lists the subtopics and displays 
the Subtopic? prompt. To get information on one of the subtopics, type the name 
after the prompt. To see information on another topic, press the Return key. You 
can now ask for information on another topic when the Help facility displays the 
Topic? prompt. Press the Return key to exit the Help facility and return to DCL 
command level. 


If you use an asterisk (*) in place of any keyword, the HELP command displays 
all information available at the level that the asterisk replaces. For example, 
HELP COPY * displays all the subtopics under the topic COPY. 


If you use an ellipsis ( ... ) immediately after any primary keyword, the Help 
facility displays all the information on the specified topic and all subtopics of that 
topic. For example, HELP COPY ... displays information on the COPY topic as 
well as information on all the subtopics under COPY. The ellipsis can only be 
used from the topic level; it cannot be used from the subtopic level. — 


The asterisk (*) and the percent sign (%) wildcard characters are allowed in the 
keyword. 


/EXACT 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string 
that must match the search string exactly and must be enclosed with quotation 
marks (“”)._ 


If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search 
mode is enabled when you set the search string with the Find (E1) key. 


/HIGHLIGHT[=keyword] 

/NOHIGHLIGHT (default) 

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of 
highlighting you want when a search string is found. When a string is found, the 
entire line is highlighted. You can use the following keywords: BOLD, BLINK, 


- REVERSE, and UNDERLINE. BOLD is the default highlighting. 


[INSTRUCTIONS (default) 

/NOINSTRUCTIONS 

Displays an explanation of the HELP command along with the list of topics (if no 
topic is specified). By default, the HELP command display includes a description 
of the facility and the format, along with the list of topics. If you specify the 
/NOINSTRUCTIONS qualifier, only the list of topics is displayed. 


/LIBLIST (default) 
/NOLIBLIST 
Displays any auxiliary help libraries. 


/LIBRARY=filespec 

/NOLIBRARY 

Uses an alternate help library instead of the default system library, 
SYS$HELP:HELPLIB.HLB. The specified library is used as the main (root) 
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help library, and is searched for Help facility anor ne UOT before any user-defined 
default help libraries are checked. 


If you omit the device and directory specification, the default is SYS$HELP, the 
logical name of the location of the system help libraries. The default file type is 
-HLB. 


The /NOLIBRARY qualifier excludes the default help library from the library 
search order. 


/IMESSAGE 
Displays descriptions of system messages. See the HELP/MESSAGE command in 
this manual. 


/OUTPUT[=filespec] 

/NOOUTPUT 

Controls where the output of the command is sent. By default, the output is sent 
to SYS$OUTPUT, the current process default output stream or device. 


If you enter the /OUTPUT qualifier with a partial file specification (for example, 
/OUTPUT=[JONES]), HELP is the default file name and LIS is the default file 
type. The asterisk (*) and the percent sign (%) wildcard characters are not 
allowed. 


If you enter the /(NOOUTPUT qualifier, output is suppressed. 


/PAGE[=keyword] 
/NOPAGE (default) 
Controls the display of information on the screen. 


You can use the following keywords with the /PAGE qualifier: 


CLEAR_SCREEN Clears the screen before each page is displayed. 
SCROLL Displays information one line at a time. 
SAVE[=n] Enables screen navigation of information, where n is the 


number of pages to store. 


The /PAGE=SAVE qualifier allows you to navigate through screens of information. 
The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of 
information. When you use the /PAGE=SAVE qualifier, you can use the following 
keys to navigate through the information: 


Key Sequence Description 


Up arrow ({), Ctrl/B — Scroll up one line. 


Down arrow (| ) Scroll down one line. 

Left arrow (+ ) Scroll left one column. 

Right arrow (— ) Scroll right one column. 

Find (E1) Specify a string to find when the information is 
displayed. 

Insert Here (E2) Scroll right one half screen. 

Remove (E3) Scroll left one half screen. 

Select (E4) Toggle 80/132 column mode. 

Prev Screen (E5) Get the previous page of information. 


HELP 


Key Sequence Description 

Next Screen (E6), Get the next page of information. 

Return, Enter, Space 

F10, Ctrl/Z Exit. (Some utilities define these differently.) 
Help (F15) Display utility help text. . 
Do (F16) Toggle the display to oldest/newest page. 
Ctrl/W Refresh the display. 


The /PAGE qualifier is not compatible with the /OUTPUT qualifier. 


/PROMPT (default) 

/NOPROMPT 

Permits you to solicit further information interactively. If you specify the 
/NOPROMPT qualifier, the Help facility returns you to DCL command level after 
it displays the requested information. 


If the /PROMPT qualifier is in effect, one of four different prompts is displayed, 
requesting you to specify a particular help topic or subtopic. Each prompt 
represents a different level in the hierarchy of help information. The four prompt 
levels are as follows: 


1. Topic?—The root library is the main library and you are not currently — 
examining the Help facility information for a particular topic. 


2. [library-spec] Topic?—The root library is a library other than the main library 
and you are not currently examining the Help facility information for a 
particular topic. 


3. [keyword] Subtopic?—The root library is the main library and you are 
currently examining the Help facility information for a particular topic (or 
subtopic). 


4. A combination of 2 and 3. 


When you encounter one of these prompts, you can enter any one of the responses 
described in the following table: 


Current 
Prompt 
Response Environment Action 
keyword([...] 1,2 Searches all enabled libraries for the keyword. 
3,4 Searches additional help libraries for the current 
. topic (or subtopic) for the keyword. 
@filespec 1,2 Same as above, except that the library specified 
keyword[...] by @filespec is now the root library. If the 


specified library does not exist, the Help facility 
treats @filespec as a normal keyword. 


Displays a list of topics available in the root 
library. 
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Current 
Prompt 
Response Environment Action 
3,4 Same as above; treats @filespec as a normal 


keyword. 


Displays the list of subtopics of the current topic 
(or subtopics) for which help exists. 


1 Exits from the Help facility. 
Changes root library to main library. 


3,4 Prompts for a topic or subtopic at the next higher 
level. 
1,2,3,4 Exits from the Help facility. 


/SEARCH="string" 

Use with the /PAGE=SAVE qualifier to specify a string that you want to findin | 
the information being displayed. Quotation marks are required for the /SEARCH 
qualifier, if you include spaces in the text string. 


You can also dynamically change the search string by pressing the Find key (E1) 
while the information is being displayed. Quotation marks are not required for a 


_dynamic search. 


/USERLIBRARY=(level[,...]) 

/NOUSERLIBRARY 

Names the levels of search for information in auxiliary libraries. The levels are 
as follows: 


PROCESS Libraries defined at process level 

GROUP Libraries defined at group level 

SYSTEM Libraries defined at system level 

ALL All libraries (default) 

NONE No libraries (same as the /NOUSERLIBRARY qualifier) 


Auxiliary help libraries are libraries defined with the logical names 
HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and so on. Libraries 

are searched for information in this order: root (current) library, main library (if 
not current), libraries defined at process level, libraries defined at group level, 
libraries defined at system level, and the root library. If the search fails, the root 
library is searched a second time so that the context is returned to the root library 
from which the search was initiated. The default is the /USERLIBRARY=ALL 
qualifier. If you specify only one level for the Help facility to search, you can omit 
the parentheses. 


/WRAP 

/NOWRAP (default) 

Use with the /PAGE=SAVE qualifier to limit the number of columns to the width 
of the screen and to wrap lines that extend beyond the width of the screen to the 
next line. 


The /NOWRAP qualifier extends lines beyond the width of the screen and can 
be seen when you use the scrolling (left and right) features provided by the 
/PAGE=SAVE qualifier. 


Examples 


1. 


HELP 


$ HELP 
HELP 


(HELP message text and list of topics) 
Topic? 


In this example, the HELP command is entered without any qualifiers or 
parameters. This example produces a display of the help topics available from 
the root help library, SYS$HELP:HELPLIB.HLB. 


If you enter one of the listed topics in response to the Topic? prompt, the Help 
facility displays information about that topic and a list of subtopics (if there 
are any). If one or more subtopics exist, the Help facility prompts you for a 
subtopic, as follows: 


Topic? ASSIGN 
ASSIGN 


(HELP message text and subtopics) 


ASSIGN Subtopic? 


If you type a subtopic name, the Help facility displays information about that 
subtopic, as follows: 


ASSIGN Subtopic? Name 
ASSIGN 
Name 


(HELP message text and subtopics, if any) 


ASSIGN Subtopic? 


If one or more sub-subtopics exist, the Help facility prompts you for a sub- 
subtopic; otherwise, as in the previous example, the facility prompts you for 
another subtopic of the topic you are currently inspecting. 


Entering a question mark (?) redisplays the Help facility message and 
options at your current level. Pressing the Return key does either of the 
following: 


¢ Moves you back to the previous help level if you are in a subtopic level. 
¢ Terminates the Help facility if you are at the first level. 
Pressing Ctrl/Z terminates the Help facility at any level. 


$ HELP COPY... 


The HELP command in this example displays a description of the COPY 
command and of the command’s parameters and qualifiers. Note that the 
ellipsis can be used only from the topic level; it cannot be used from the 
subtopic level. 
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3. 


$ HELP/NOPROMPT ASSIGN/GROUP 


(ASSIGN/GROUP HELP message) 


$ 
§ HELP/NOPROMPT/PAGE EDIT * 
(HELP messages on all first-level EDIT subtopics) 
$ 
The two HELP commands request help on specific topics. In each case, the 


HELP command displays the help message you request and then returns you 
to DCL command level and the dollar sign prompt ($). 


The first command requests help on the /GROUP qualifier of the ASSIGN 
command. The asterisk (*) in the second example is a wildcard character. 

It signals the Help facility to display information about all EDIT subtopics, 
which are then displayed in alphabetical order. The /NOPROMPT qualifier 
suppresses prompting in both sample commands. The /PAGE qualifier on the 
second HELP command causes output to the screen to stop after each screen 
of information is displayed. 


$ HELP FILL 
Sorry, no documentation on FILL 
Additional information available: 


(list of first-level topics ) 


Topic? @EDTHELP FILL 
FILL 


(FILL HELP message) 
@EDTHELP Topic? 


When you enter a request for help on a topic that is not in the default help 
library, you can instruct the Help facility to search another help library for 
the topic. In this example, entering the command @EDTHELP FILL instructs 
the Help facility to search the help library SYS$HELP:EDTHELP.HLB for 
information on FILL, an EDT editor command. The Help facility displays the 
message and prompts you for another EDT editor topic. 


$ SET DEFAULT SYSSHELP 

$ DEFINE HLPSLIBRARY EDTHELP 

$ DEFINE HLPSLIBRARY 1 MAILHELP 

$ DEFINE HLPS$LIBRARY 2 BASIC 

$ DEFINE HLP$LIBRARY_ 3 DISK2:[{MALCOLM]FLIP 
$ HELP REM 


You can use logical names to define libraries for the Help facility to search 
automatically if it does not find the specified topic in the OpenVMS root 
help library. This sequence of commands instructs the Help facility to search 
libraries in addition to the default root library, SYS$HELP:HELPLIB.HLB. 


The four DEFINE statements create logical names for the four user-defined 
help libraries that the Help facility is to search after it has searched the 

root library. The first three entries are help libraries in the current default 
directory. By default, the Help facility searches for user-defined help libraries 
in the directory defined by the logical name SYS$HELP. The fourth entry is 
the help library FLIP.HLB in the directory DISK2:[MALCOLM]. Note that the 


HELP 


logical names that you use to define these help libraries must be numbered 
consecutively; that is, you cannot skip any numbers. 


The Help facility first searches the root library for REM. It then searches 
the libraries HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and 

so on, until it finds REM or exhausts the libraries it knows it can search. 
When it finds REM in the BASIC.HLB library, the Help facility displays the 
appropriate help information and prompts you for a subtopic in that library. 
If you request information on a topic not in the BASIC.HLB library, the Help 
facility once again searches the help libraries you have defined. 
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Displays descriptions of system messages. 
HELP/MESSAGE _[/qualifier [...]] [search-string] 


search-string 

Specifies a message identifier or one or more words from a message’s text. By 
default, HELP/MESSAGE displays a description of the message produced by the 
last executed command (that is, the message corresponding to the value currently 
stored in the CLI symbol $STATUS). 


The Help Message utility (MSGHLP) operates on the search string using the 
following conventions: 


e Words containing fewer than three alphanumeric characters are ignored. 


e Words can be listed in any order. 


You can minimize search time by specifying the most unusual word first. 


¢ Nonalphanumeric characters are ignored in the search. Exceptions are the 
percent sign (%) and hyphen (-) when they prefix a message. Therefore, you 
can paste a full message into the search string, provided you include these 
special characters and delete any variables (such as file names) that were 
inserted into the message. 


If Help Message fails to find a pasted message in the database, submit the 
command again and omit the leading special character, facility, and severity. 
Some common messages are documented as "shared" messages rather than 
facility-specific messages. 


e Help Message matches all words that begin with the characters specified in 
the search string. Use /WORD_MATCH=WHOLE_WORD to specify that only 
whole words be matched. 


The Help Message utility accesses message descriptions in a text file. This text 
file is derived from the latest OpenVMS system messages documentation, 

and, optionally, from other source files, including user-supplied message 
documentation. By default, Help Message provides information on how the 
last executed command completed. 


You can extract all messages produced by one or more specified facilities. By 
directing this output to a file, you can create and print your own customized 
message documentation. 


For full details about adding comments or messages to the Help Message 
database, refer to the OpenVMS System Messages: Companion Guide for Help 
Message Users. 


Qualifiers 


HELP/MESSAGE 


/BRIEF 
Outputs the message text only. 


/DELETE=filename.MSGHLP 
Deletes all messages contained in the specified .MSGHLP file from whichever of 
the following files is found first: 


e A .MSGHLP$DATA file specified with the /LIBRARY qualifier 


e The first MSGHLP$DATA file in a search path specified by the (LIBRARY 
qualifier 


e The first IMSGHLP$DATA file in the default search path (defined by logical 
name MSGHLP$LIBRARY) 


¢ SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA (the default 
-MSGHLP$DATA file) 


You must have write access to Digital-supplied .MSGHLP$DATA files to delete 
messages from the Digital-supplied database. 


Note 


If you create a .MSGHLP file by specifying a search string, check 

the output .MSGHLP file to be sure the search did not pick up any 
unexpected messages that you do not want to delete from the database. 
Edit any such messages out of the .MSGHLP file before you perform the 
delete operation. 


/EXTRACT=filename.MSGHLP 

Extracts messages from the database and generates a .MSGHLP file that can 
be edited, if desired, and used as input for /INSERT and /DELETE operations. 
/EXTRACT retrieves data from a .MSGHLP$DATA file or logical search path 
specified by /LIBRARY or, by default, from files in the search path defined 

by logical name MSGHLP$LIBRARY. When /EXTRACT is not specified, Help 
Message produces output in standard text format by default (see /OUTPUT). 


/FACILITY=? 

/FACILITY=(facility-name [,...]) 

/FACILITY=ALL 

Specifies which facilities in the database are to be searched for a match. 


Enter /FACILITY=? to output a list of all facilities in the default database or in a 
database specified by /LIBRARY. 


To narrow your search, specify one or more facility names with /FACILITY. 
(Multiple facilities must be enclosed in parentheses and be separated by commas.) 
Help Message then outputs only matching messages produced by the specified 
facility or facilities. 


Specify /FACILITY=ALL to output messages for all facilities in the database. 
/FACILITY=ALL is the default unless another facility is implied; for example, 
specifying /STATUS or defaulting to the value of the CLI symbol $STATUS 
automatically identifies a specific facility. Similarly, cutting and pasting a 
message that includes a facility name invalidates use of the /FACILITY qualifier. 
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_ See the OpenVMS System Messages: Companion Guide for Help Message Users 


for more details about using the /FACILITY qualifier. 


/FULL (default) 
Outputs the complete message description, including message text, facility name, 
explanation, user action, and user-supplied comment, if any. 


ANSERT=filename.MSGHLP 

JINSERT=TT: 

Updates the first of the following files to be found with new or changed 
information from the specified .MSGHLP file, or, if TT: is specified, with the 
data entered immediately at the terminal: 


° A MSGHLP$DATA file specified with the /LIBRARY qualifier 


e The first .MSGHLP$DATA file in a search path specified by the /LIBRARY 
qualifier 


e The first .IMSGHLP$DATA file in the default search path (defined by logical 
logical name MSGHLP$LIBRARY) 


e SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA (the default 
-MSGHLP$DATA file) 


You must have write access for the Digital-supplied .MSGHLP$DATA files to 
insert data into these files. User-supplied data is identified by change bars in 
Help Message output. 


/LIBRARY=disk:[directory]filename.MSGHLP$DATA 

/LIBRARY=disk:[directory] 

/LIBRARY=logical-name 

Defines the messages database for the current command to be a particular 
.MSGHLP$DATA file, all the .MSGHLP$DATA files in a specified directory, or all 
the files in a search path defined by a logical name. 


For most operations, the default database is either 
SYSSHELP:MSGHLP$LIBRARY.MSGHLP$DATA or a search path of 
-.MSGHLP$DATA files defined by the logical name MSGHLP$LIBRARY. 


For /DELETE and /INSERT operations, the default database is either 
SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA or the first file in a search 
path defined by the logical name MSGHLP$LIBRARY. 


/OUTPUT=filespec 

Writes output to the specified file. By default, Help Message writes output to 
SYS$OUTPUT, which is normally the terminal. (Use of /OUTPUT=filespec is 
incompatible with /PAGE.) 


/PAGE (default for screen display) 

/NOPAGE 

Displays terminal output one screen at a time. The page length is automatically 
set to 1 line less than the value specified by SET TERMINAL/PAGE. (Use of 
/PAGE is incompatible with /OUTPUT=filespec.) 


- /SECTION_FILE=* 


/SECTION_FILE=file-spec 

Identifies the specified message section file to the system so that Help Message 
can interpret the $STATUS values for the messages in that file. The default 
file specification is SYS$MESSAGE:.EXE. Specifying /SECTION_FILE=* _ 


Examples 


HELP/MESSAGE 


automatically includes all OpenVMS-supplied message section files. For more 
information, see OpenVMS System Messages: Companion Guide for Help Message 
Users. 


/SORT 

/NOSORT (default) 

Sorts output in alphabetical order. If a sort fails, retry the aperaizon using the 
/WORK_FILES qualifier. 


/STATUS=status-code 

/STATUS=’symbol’ 

ISTATUS=’$STATUS’ (default) 

Outputs the message corresponding to the specified status code. You can specify 
the status code with a decimal or hexadecimal number or a symbol enclosed in 
apostrophes. You can omit leading zeros, but you must prefix any hexadecimal 
number with "%X". 


If a HELP/MESSAGE command does not include a search string, Help Message 
by default outputs the message corresponding to the CLI symbol $STATUS; 
that is, Help Message displays information on how the last executed command 
completed. 


You cannot specify a search string or /FACILITY with /STATUS. /FACILITY is 
also illegal if you omit the search string and default to /STATUS="$STATUS’. 


/WORD_MATCHG2INITIAL_SUBSTRING (default) | 
/WORD_MATCH=WHOLE_WORD 

/WORD_MATCH=INITIAL_SUBSTRING matches all words that begin with a 
word specified in the search string. The search string can contain multiple words 
to be matched. Only messages that match every word in the search string (in any 
order) are output. 


/WORD_MATCH=WHOLE_WORD matches whole words only and refines your 
search to the exact words specified. For example, an exact search on ACC screens 
out dozens of other messages containing words that begin with the letters ACC. 


/WORK_FILES=nn 

/WORK_FILES=0 (default if qualifier is omitted) . 

/WORK_FILES=2 (default if qualifier is entered with no value) 

Specifies that work files are to be used if the /SORT qualifier is specified. You can 
specify a value from 0 to 10 for nn. This qualifier has no effect if /SORT is not 
specified. 


1. $ SHOW DEVICE KUDOS 
¢SYSTEM-W-NOSUCHDEV, no such device available 
$ HELP/MESSAGE 
The first command creates an error. The default HELP/MESSAGE command 
(with no qualifiers) displays a description of the SYSTEM facility message 
NOSUCHDEV. 
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$ HELP/MESSAGE ACCVIO 

$ HELP/MESSAGE/BRIEF ACCVIO 

$ HELP/MESSAGE/FACILITY=SYSTEM ACCVIO 
$ HELP/MESSAGE VIRTUAL ACCESS 

$ HELP/MESSAGE/STATUS=12 

$ HELP/MESSAGE/STATUS=$XC 


These commands demonstrate how you can use various qualifiers to access 
and display the ACCVIO message (sometimes several!) in different formats. 


$ HELP/MESSAGE/BRIEF ACC 
$ HELP/MESSAGE/BRIEF/WORD_MATCH=WHOLE WORD ACC 


In the first command, Help Message by default matches dozens of words 


beginning with the string “ACC.” The /(WORD_MATCH=WHOLE_WORD 
qualifier dramatically refines the search to match the exact word only. 


$ HELP/MESSAGE/FACILITY=(BACKUP , SHARED) /SORT/OUTPUT=MESSAGES . TXT 


This command selects all messages issued by the BACKUP facility and those 
messages documented as “Shared by several facilities,” alphabetizes them, 
and outputs them to a printable file called MESSAGES.TXT. 


By selecting the messages you want and directing them to a file, you can 
create and print your own customized messages documentation. 


$ HELP/MESSAGE/EXTRACT=BADMESSAGE.MSGHLP BADMESSAGE 
$ HELP/MESSAGE/DELETE=BADMESSAGE . MSGHLP- 
_$ /LIBRARY=SYS$LOGIN : MYMESSAGES . MSGHLP$DATA 
$ CONVERT SYSSLOGIN:MYMESSAGES .MSGHLPSDATA- 
$ SYS$LOGIN:MYMESSAGES .MSGHLPSDATA 
$ PURGE SYSSLOGIN:MYMESSAGES .MSGHLPS$DATA 
$ HELP/MESSAGE/INSERT=BADMESSAGE .MSGHLP 


The first command in this sequence extracts the hypothetical message . 
BADMESSAGE from the default database and outputs it to file 
BADMESSAGE.MSGHLP. 


The second command uses the BADMESSAGE.MSGHLP file to delete the 
BADMESSAGE description from the MYMESSAGES.MSGHLP$DATA file 
specified by the /LIBRARY qualifier. 


The next two commands compress the MYMESSAGES.MSGHLP$DATA file 
to save disk space after the deletion. 


The last command uses the BADMESSAGE.MSGHLP file (possibly an edited 
version at a later time) to insert the BADMESSAGE message into the default 
.MSGHLP$DATA file. 


$ HELP/MESSAGE/EXTRACT=NOSNO.MSGHLP NOSNO 

$ EDIT/EDT NOSNO.MSGHLP 

1NOSNO, can’t ski; no snow 

2XCSKI, XCSKI Program 

3Your attempt to ski failed because there is no snow. 
4Wait until there is snow and attempt the operation again. 
5If you don’t want to wait, go to a location where there is 
5snow and ski there. 

5 

50r, try ice skating instead! 

[EXIT] 

$ HELP/MESSAGE/INSERT=NOSNO.MSGHLP 


HELP/MESSAGE 


This command sequence shows how users with write access to Digital- 
supplied .MSGHLP$DATA files can add a comment to a Digital-supplied 
message. 


The first command extracts hypothetical message NOSNO to file 
NOSNO.MSGHLP. The second command edits the .MSGHLP file to add 
a comment at the end of the message. Each comment line, even blank 
lines, includes a “5” prefix. The next command updates the database by 
using NOSNO.MSGHLP to insert the updated message into the default 
-MSGHLP$DATA file. 
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Tests the value of an expression and, depending on the syntax specified, executes 
the following: 


e One command following the THEN keyword if the expression is true 
¢ Multiple commands following the $THEN command if the expression is true 


e¢ One or more commands following the $ELSE command if the expression is 
false 


$ IF expression THEN [$] command 
or 

$ IF expression 

$ THEN [command] 


command 


$ [ELSE] [command] 


command 


$ ENDIF 


Note 


Digital advises against assigning a symbolic name that is already a DCL 

command name. Digital especially discourages the assignment of symbols 
such as IF, THEN, ELSE, and GOTO, which can affect the interpretation 
of command procedures. 


expression 

Defines the test to be performed. The expression can consist of one or more 
numeric constants, string literals, symbolic names, or lexical functions separated 
by logical, arithmetic, or string operators. 


Expressions in IF commands are automatically evaluated during the execution of 
the command. Character strings beginning with alphabetic characters that are 
not enclosed in quotation marks (“ ”) are assumed to be symbol names or lexical 
functions. The command language interpreter (CLI) replaces these strings with 
their current values. 


Description 


Examples 


IF 


Symbol substitution in expressions in IF commands is not iterative; that is, each 
symbol is replaced only once. However, if you want iterative substitution, precede 
a symbol name with an apostrophe (’) or ampersand (&). 


The command interpreter does not execute an IF command when it contains an 
undefined symbol. Instead, the command interpreter issues a warning message 
and executes the next command in the procedure. 


For a summary of operators and details on how to specify expressions, see the 
OpenVMS User’s Manual. 


command 
Specifies the DCL command or commands to be executed, depending on the 
syntax specified, when the result of the expression is true or false. 


The IF command tests the value of an expression and executes a given command 
if the result of the expression is true. The expression is true if the result has an 
odd integer value, a character string value that begins with the letters Y, y, T, or 
t, or an odd numeric string value. 


The expression is false if the result has an even integer value, a character string 
value that begins with any letter except Y, y, T, or t, or an even numeric string 
value. 


1. $ COUNT = 0 
$ LOOP: 
= COUNT + 1 


$ COUNT 


$ IF COUNT .LE. 10 THEN GOTO LOOP 
$ EXIT 


This example shows how to establish a loop in a command procedure, using 
a symbol named COUNT and an IF statement. The IF statement checks the 
value of COUNT and performs an EXIT command when the value of COUNT 
is greater than 10. 


2. $ IF Pl .EQS. "" THEN GOTO DEFAULT 
$ IF (Pl .EQS. "A") .OR. (Pl .EQS. "B") THEN GOTO ‘Pl’ 
$ WRITE SYSSOUTPUT "Unrecognized parameter option ''Pl’ " 


$ EXIT 
$ A: ! Process option a 
$ EXIT 
$ B: ! Process option b 
$ EXIT 


$ DEFAULT: ! Default processing 


$ EXIT 
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This example shows a command procedure that tests whether a parameter 
was passed. The GOTO command passes control to the label specified as the 
parameter. 


If the procedure is executed with a parameter, the procedure uses that 
parameter to determine the label to branch to. For example: 


@TESTCOM A 


When the procedure executes, it determines that P1 is not null, and branches 
to the label A. Note that the EXIT command causes an exit from the 
procedure before the label B. 


_ $ SET NOON 


$ LINK CYGNUS, DRACO, SERVICE/LIBRARY 
$ IF SSTATUS 
$ THEN 

$ RUN CYGNUS 

$ ELSE 

$ WRITE SYS$OUTPUT "LINK FAILED" 

$ ENDIF 

$ EXIT 


This command procedure uses the SET NOON command to disable error 
checking by the command procedure. After the LINK command, the IF 
command tests the value of the reserved global symbol $STATUS. If the value 
of $STATUS indicates that the LINK command succeeded, then the program 
CYGNUS is run. If the LINK command returns an error status value, the 
command procedure issues a message and exits. 
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Format 


Parameters 


Formats a disk or magnetic tape volume, writes a label on the volume, and leaves 
the disk empty except for the system files containing the structure information. 
All former contents of the disk are lost. 


Requires VOLPRO (volume protection) privilege for most INITIALIZE 
command operations. 


INITIALIZE device-name[:] volume-label 


device-name[:] 
Specifies the name of the device on which the volume to be initialized is physically 
mounted. 


The device does not have to be allocated currently; however, allocating the device 
before initializing it is the recommended practice. 


volume-label 

Specifies the identification to be encoded on the volume. For a disk volume, you 
can specify a maximum of 12 ANSI characters; for a magnetic tape volume, you 
can specify a maximum of 6 alphanumeric characters. Letters are automatically 


_ changed to uppercase. DIGITAL strongly recommends that a disk volume label 


Description 


should only consist of alphanumeric characters, dollar signs ($), underscores (_), 
and hyphens (-). 


To use ANSI “a” characters on the volume label on magnetic tape, you must 
enclose the volume name in quotation marks (“”). For an explanation of ANSI 
“a” characters, see the description of the /LABEL qualifier. 


The default format for disk volumes in the OpenVMS operating system is called 
the Files—11 On-Disk Structure Level 2. The default for magnetic tape volumes is 
based on Level 3 of the ANSI standard for magnetic tape labels and file structure 
for informational interchange (ANSI X3.27-1978). 


The INITIALIZE command can also initialize disk volumes in the Files—11 
On-Disk Structure Level 1 format. 


You must have VOLPRO privilege to initialize a volume, except in the following 
cases: 


e A blank disk or magnetic tape volume; that is, a volume that has never been 
written . 


e A disk volume that is owned by your current user identification code (UIC) or 
by the UIC [0,0] : 


e A magnetic tape volume that allows write (W) access to your current UIC 
that was not protected when it was initialized 


After the volume is initialized and mounted, the SET SECURITY command may 
be used to modify the security profile. 
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When the INITIALIZE command initializes a magnetic tape volume, it always 
attempts to read the volume. A blank magnetic tape can sometimes cause 
unrecoverable errors, such as the following: 


e An invalid volume number error message: 
SINIT-F-VOLINV, volume is invalid 


e A runaway magnetic tape (this frequently occurs with new magnetic tapes 
that have never been written or that have been run through verifying 
machines). You can stop a runaway magnetic tape only by setting the 
magnetic tape drive off line and by then putting it back on line. 


If this type of unrecoverable error occurs, you can initialize successfully a 
magnetic tape by repeating the INITIALIZE command from an account that has 
VOLPRO (volume protection) privilege and by specifying the following qualifier in 
the command: 


/OVERRIDE=(ACCESSIBILITY,EXPIRATION) 


This qualifier ensures that the INITIALIZE command does not attempt to verify 
any labels on the magnetic tape. 


If you have VOLPRO privilege, the INITIALIZE command initializes a disk 


- without reading the ownership information. If you do not have VOLPRO 


privilege, the INITIALIZE command checks the ownership of the volume before 
initializing the disk. A blank disk or a disk with an incorrect format can 
sometimes cause a fatal drive error. If a blank disk or a disk with an incorrect 
format causes this type of error, you can initialize a disk successfully by repeating 
the INITIALIZE command with the /DENSITY qualifier from an account that has 
VOLPRO privilege. 


Many of the INITIALIZE command qualifiers allow you to specify parameters 
that can maximize input/output (I/O) efficiency. 


/ACCESSED=number-of-directories 
Affects Files-11 On-Disk Structure Level 1 disks only. 


Specifies that, for disk volumes, the number of directories allowed in system 
space must be a value from 0 to 255. The default value is 3. 


/BADBLOCKS=(areajJ....]) 
Specifies, for disk volumes, faulty areas on the volume. The INITIALIZE 
command marks the areas as allocated so that no data is written in them. 


Possible formats for area are as follows: 


Ibn[:count] Logical block number (LBN) of the first block and 
optionally a block count beginning with the first 
block, to be marked as allocated 


sec.trk.cyl[:cnt] Sector, track, and cylinder of the first block, and 
optionally a block count beginning with the first 
block, to be marked as allocated 


All media supplied by Digital and supported on the OpenVMS operating system, 
except diskettes and TU58 cartridges, are factory formatted and contain bad 
block data. The Bad Block Locator utility (BAD) or the diagnostic formatter 
EVRAC can be used to refresh the bad block data or to construct it for the media 
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exceptions above. The /BADBLOCKS qualifier is necessary only to enter bad 
blocks that are not identified in the volume’s bad block data. 


DIGITAL Storage Architecture (DSA) disks (for example, disks attached to UDA- 
50 and HSC50 controllers) have bad blocks handled by the controller, and appear 
logically perfect to the file system. 


For information on how to run BAD, see the OpenVMS Bad Block Locator Utility 
Manual. 


/CLUSTER_SIZE=number-of-blocks 

Defines, for disk volumes, the minimum allocation unit, in blocks. The maximum 
size you can specify for a volume is one-hundredth the size of the volume; the 
minimum size you can specify is calculated with the following formula: 


disk size(number of blocks) 
255 *« 4096 


For Files-11 On-Disk Structure Level 2 disks, the VMScluster size default 
depends on the disk capacity; disks with less than 50,000 have a default of 1. 
Disks that are larger than 50,000 have a default of 3, unless this default would 
break the formula. In this case the minimum value allowed by the equation 
above is applied. 


For Files—11 On-Disk Structure Level 1 disks, the VAXcluster size must always 
be 1. 


/DATA_CHECK[=(optionf....])] 
Checks all read and write operations on the disk. By default, no data checks are 
made. Specify one or both of the following options: 


READ Checks all read operations. 


WRITE Checks all write operations; default if only the (DATA. CHECK 
qualifier is specified. 


To override the checking you specify at initialization for disks, enter a MOUNT 
command to mount the volume. 


/DENSITY=density-value 
The /DENSITY qualifier is not applicable to any TK or TF tape device. 


Valid density values are as follows: 


800 6250 HD SINGLE 
1600 DD ED DOUBLE 


To format a diskette on RXnn diskette drives, use the INITIALIZE/DENSITY 
command. Specify the density at which the diskette is to be formatted as follows: 


Diskette Density value 


RX02 SINGLE or DOUBLE 
RX33 DOUBLE 
RX26 ED 


If you do not specify a density value for a diskette being initialized on a drive, the 
system leaves the volume at the density to which the volume was last formatted. 
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Note 


Diskettes formatted in double density cannot be read or written by the 
console block storage device (an RX01 drive) of a VAX—11/780 until they 
have been reformatted in single density. 


RX833 diskettes cannot be read from or written to by RX50 disk drives. 
RX50 diskettes can be read from and written to by RX33 disk drives; they 
cannot be formatted by RX83 disk drives. 


For magnetic tape volumes, specifies the density in bits per inch (bpi) at which 
the magnetic tape is to be written. 


For magnetic tape volumes, the density value specified can be 800 bpi, 1600 bpi, 
or 6250 bpi, as long as the density is supported by the magnetic tape drive. If 
you do not specify a density value for a blank magnetic tape, the system uses a 
default density of the highest value allowed by the tape drive. If the drive allows 
6250-, 1600-, and 800-bpi operation, the default density is 6250 bpi. If you do 
not specify a density value for a magnetic tape that has been previously written, 
the system uses the density of the first record on the volume. If the record is 
unusually short, the density value will not default. 


/DIRECTORIES=number-of-entries 

Specifies, for disk volumes, the number of entries to preallocate for user 
directories. The number of entries must be an integer between 16 and 16000. 
The default value is 16. 


/ERASE 

/NOERASE (default) 

Physically destroys deleted data by writing over it. Controls the data security 
erase (DSE) operation on the volume before initializing it. The /ERASE qualifier 
applies to Files—11 On-Disk Structure Level 2 disk and ANSI magnetic tape 
volumes, and is valid for magnetic tape devices that support the hardware erase 
function, such as TU78 and MSCP magnetic tapes. 


If you specify the /ERASE qualifier, a DSE operation is performed on the volume. 
For disk devices, the ERASE volume attribute is set. In effect, each file on the 
volume is erased when it is deleted. 


Note that the amount of time taken by the DSE operation depends on the volume 
size; the INITIALIZE/ERASE command is always slower than the INITIALIZE 
/NOERASE command. 


/EXTENSION=number-of-blocks 

Specifies, for disk volumes, the number of blocks to use as a default extension size 
for all files on the volume. The extension default is used when a file increases to a 
size greater than its initial default allocation during an update. For Files—11 On- 
Disk Structure Level 2 disks, the value for the number-of-blocks parameter can 
range from 0 to 65,535. The default value is 5. For Files—11 On-Disk Structure 
Level 1 disks, the value can range from 0 to 255. 


The OpenVMS operating system uses the default volume extension only if no 
different extension has been set for the file and no default extension has been set 
for the process by using the SET RMS_DEFAULT command. 


/FILE_PROTECTION=code 
Affects Files-11 On-Disk Structure Level 1 disks only. 


INITIALIZE 


Defines for disk volumes the default protection to be applied to all files on the 
volume. 


Specify the code according to the standard syntax rules described in the 
OpenVMS Guide to System Security. Any attributes not specified are taken 
from the current default protection. 


Note that this attribute is not used when the volume is being used on an 
OpenVMS system, but is provided to control the process’s use of the volume on 
RSX-11M systems. OpenVMS systems always use the default file protection. Use 
the SET PROTECTION/DEFAULT command to change the default file 

protection. . 


/GROUP 

Used in conjunction with the /NOSHARE qualifier to create a group volume. The 
group volume allows access by system (S), owner (O), and group (G) accessors. 
The protection is (S:RWCD,O:RWCD,G:RWCD,W). 


The owner user identification code (UIC) of the volume defaults to your group 
number and a member number of 0. 


/HEADERS=number-of-headers 

Specifies, for disk volumes, the number of file headers to be allocated for the 
index file. The minimum and default value is 16. The maximum is the value set 
with the /MAXIMUM_FILES qualifier. 


This qualifier is useful when you want to create a number of files and want to 
streamline the process of allocating space for that number of file headers. If you 
do not specify this qualifier, the file system dynamically allocates space as it is 
needed for new headers on the volume. 


Note 
The default value for the /HEADER qualifier is generally insufficient 
for ODS-2 disks. To improve performance and avoid SYSTEM-F- 
HEADERFULL errors, Digital recommends that you set this value to 
be approximately the number of files that you anticipate having on your 


disk. However, grossly overestimating this value will result in wasted 
disk space. 


The /HEADER qualifier controls how much space is initially allocated to 
INDEXF-.SYS for headers. Each file on a disk requires at least one file header and 
each header occupies one block within INDEXF.SYS. Files that have many Access 
Control Entries (ACE) or are very fragmented may use more than one header. 


The default value of 16 leaves room for less than 10 files to be created before 
INDEXF-.SYS must extend. Therefore, try to estimate the total number of files 
that will be created on the disk and specify it here. This will improve disk access 
performance. Over-estimating the value may lead to wasted disk space. This 
value cannot be changed without reinitializing the volume. 


INDEXE-.SYS is limited as to how many times it may extend. When the map area 
in its header (where the retrieval pointers are stored) becomes full, file creation 
fails with the message "SYSTEM-W-HEADERFULL." 
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/HIGHWATER (default) 
/NOHIGHWATER 
Affects Files-11 On-Disk Structure Level 2 disks only. 


Sets the file high-water mark (FHM) volume attribute, which guarantees that 
users cannot read data that they have not written. You cannot specity: the 
/NOHIGHWATER qualifier for magnetic tape. 


The /NOHIGHWATER qualifier disables FHM for a disk volume. 
/AINDEX=position 


Specifies the location of the index file for the volume’s directory structure. 
Possible positions are as follows: 


BEGINNING _ Beginning of the volume 


MIDDLE Middle of the volume (default) 
END End of the volume 
BLOCK:n Beginning of the logical block specified by n 


/LABEL=option 
Defines characteristics for the magnetic tape volume label, as directed by the 
included option. The available options are as follows: 


¢ OWNER_IDENTIFIER:“(14 ANSI characters)” 


Allows you to specify the Owner Identifier field in the volume label. The field 
specified can accept up to 14 ANSI characters. 


e¢ VOLUME_ACCESSIBILITY:“character” 


Specifies the character to be written in the volume acoeauibility field of 

the OpenVMS ANSI volume label VOL1 on an ANSI magnetic tape. The 
character may be any valid ANSI “a” character. This set of characters 
includes numeric characters, uppercase letters, and any one of the following 
nonalphanumeric characters: 


Tae ae CO 2, ee Qe Sa a, eg 


By default, the OpenVMS operating system provides a routine that checks 
this field in the following manner. 


e Ifthe magnetic tape was created on a version of the OpenVMS operating 
system that conforms to Version 3 of ANSI, then this option must be used 
to override any character other than an ASCII space. 


¢ Ifa protection is specified and the magnetic tape conforms to an ANSI 
standard that is later than Version 3, then this option must be used to 
override any character other than an ASCII 1. 


If you specify any character other than the default, you must specify the 
/OVERRIDE=ACCESSIBILITY qualifier on the INITIALIZE and MOUNT 
commands in order to access the magnetic tape. 


/MAXIMUM_FILES=n 
Restricts the maximum number of files that the volume can contain. The 
/MAXIMUM_FILES qualifier overrides the default value, which is calculated as 


follows: , 
volume size in blocks 


(cluster factor + 1) «2 
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The maximum size you can specify for any volume is as follows: 


volume size in blocks 
(cluster factor + 1) 


The minimum value is 0. Note that the maximum can be increased only by 
reinitializing the volume. 


Note 


The MAXIMUM_FILES qualifier does not reserve or create space for new 
file headers on a volume. The file system dynamically allocates space as 
it is needed for new headers. 


/MEDIA_FORMAT=[NO]COMPACTION 

Controls whether data records are automatically compacted and blocked together 
on any device that supports data compaction. Data compaction and record 
blocking increase the amount of data that can be stored on a single tape cartridge. 


Note that once data compaction or non-compaction has been selected for a given 
cartridge, that same status applies to the entire cartridge. 


/OVERRIDE=(option{....]) 

Requests the INITIALIZE command to ignore data on a magnetic tape volume 
that protects it from being overwritten. You can specify one or more of the 
following options: 


ACCESSIBILITY (For magnetic tapes only.) If the installation allows, 
this option overrides any character in the Accessibility 
field of the volume. The necessity of this option is 
defined by the installation. That is, each installation 
has the option of specifying a routine that the magnetic 
tape file system will use to process this field. By 
default, OpenVMS provides a routine that checks this 
field in the following manner. If the magnetic tape 
was created on a version of OpenVMS that conforms 
to Version 3 of ANSI, this option must be used to 
override any character other than an ASCII space. Ifa 
protection is specified and the magnetic tape conforms 
to an ANSI standard that is higher than Version 3, this 
option must be used to override any character other 
than an ASCII 1. To use the ACCESSIBILITY option, 
you must have the user privilege VOLPRO or be the 
owner of the volume. 


EXPIRATION (For magnetic tapes only.) Allows you to write to a tape 
that has not yet reached its expiration date. You may 
need to do this for magnetic tapes that were created 
before VAX/VMS Version 4.0 on Digital operating 
systems using the D% format in the volume Owner 
Identifier field. You must have the user privilege 
VOLPRO to override volume protection, or your UIC 
must match the UIC written on the volume. 
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OWNER_IDENTIFIER Allows you to override the processing of the Owner 
Identifier field of the volume label. 


If you specify only one option, you can omit the parentheses. 


To initialize a volume that was initialized previously with the /PROTECTION 
qualifier, your UIC must match the UIC written on the volume or you must have 
VOLPRO privilege. 


You can initialize a volume previously initialized with /PROTECTION if you have 
control access. 


/OWNER_UIC=uic 

Specifies an owner user identification code (UIC) for the volume. The default is 
your default UIC. Specify the UIC using standard UIC format as described in the 
OpenVMS Guide to System Security. 


For magnetic tapes, no UIC is written unless protection on the magnetic tape is 
specified. If protection is specified, but no owner UIC is specified, your current 
UIC is assigned ownership of the volume. 


/PROTECTION=(ownership[:access][,...]) 
Applies the specified protection to the volume. 


¢ Specify the ownership parameter as system (S), owner (O), group (G), or 
world (W). 


¢ Specify the access parameter as read (R), write (W), create (C), or delete 
(D). 


The default is your default protection. Note that the /GROUP, /SHARE, and 
/SYSTEM qualifiers can also be used to define protection for disk volumes. 


For magnetic tape, the protection code is written to an OpenVMS specific volume 
label. The system applies only read (R) and write (W) access restrictions; create 
and delete (D) access are meaningless. Moreover, the system and the owner are 
always given both read (R) and write (W) access to magnetic tapes, regardless of 
the protection code you specify. 


For more information on specifying protection code, see the OpenVMS Guide to 
System Security. Any attributes not specified are taken from the current default 
protection. 


When you specify a protection code for an entire disk volume, the access type E 
(execute) indicates create access. 


/SHARE (default) 

/INOSHARE 

Permits all categories of access by all categories of ownership. The /NOSHARE 
qualifier denies access to group (unless the /GROUP qualifier is also specified) 
and world processes. 


/SIZE=n 

Specifies the size of the DECram disk (device type DT$_RAM_DISK) to be 
allocated from available memory. The size of the device is created at disk 
initialization time. Note that n cannot exceed 524,280 blocks. To deallocate 
space, specify /SIZE=0. All resources specifically allocated to the DECram disk 
are returned to the system. 
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/STRUCTURE=level 

Specifies whether the volume should be formatted in Files—11 On-Disk Structure 
Level 1 or 2 (the default). Structure Level 1 is incompatible with the /DATA_ 
CHECK and /CLUSTER_SIZE qualifiers. The default protection for a Structure 
Level 1 disk is full access to system, owner, and group, and read (R) access to all 
other users. 


Note that Alpha does not support File-11 On-Disk Structure Level 1 disks. 
Specifying 1 on Alpha results in an error. 


ISYSTEM 
Requires a system UIC or SYSPRV (system privilege) privilege. 


Defines a system volume. The owner UIC defaults to [1,1]. Protection defaults. 
to complete access by all ownership categories, except that only system processes 
can create top-level directories. 


/USER_NAME=name 
Specifies a user name to be associated with the volume. The name must be 1 to 
12 alphanumeric characters. The default is your user name. 


/VERIFIED 

/NOVERIFIED 

Indicates whether the disk has bad block data on it. Use the /NOVERIFIED 
qualifier to ignore bad block data on the disk. The default is the /VERIFIED 
qualifier for disks with 4096 blocks or more and the /NOVERIFIED qualifier for 
disks with less than 4096 blocks. 


/WINDOWS=n 
Specifies the number of mapping pointers (used to access data in the file) to be 
allocated for file windows. The value can be an integer in the range of 7 to 80. 


The default is 7. 


1. $ INITIALIZE/USER_NAME=CPA $FLOPPY1 ACCOUNTS 


Initializes the volume on $FLOPPY1, labels the volume ACCOUNTS, and 
gives the volume a user name of CPA. 


2. $ ALLOCATE DMA2: TEMP 
_DMA2: ALLOCATED 
$ INITIALIZE TEMP: BACK UP FILE 
$ MOUNT TEMP: BACK_UP FILE 
$MOUNT-I-MOUNTED, BACK UP FILE mounted on _DMA2: 
$ CREATE/DIRECTORY TEMP: [ARCHIE] 


The previous sequence of commands shows how to initialize anRKO6/RKO7 
volume. First, the device is allocated, to ensure that no one else can access it. 
Then, when the volume is physically mounted on the device, the INITIALIZE 
command initializes it. When the volume is initialized, the MOUNT command 
makes the file structure available. Before you can place any files on the 
volume, you must create a directory, as shown by the CREATE/DIRECTORY 
command. 
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3. 


$ ALLOCATE MT: 
_MTB1: ALLOCATED 
$ INITIALIZE MTB1: SOURCE 
$ MOUNT MTB1: SOURCE 
t$MOUNT-I-MOUNTED, SOURCE mounted on MTB1: 
$ COPY *.FOR MTB1: 
$ DIRECTORY MTB1: 


$ DISMOUNT MTB1: 


These commands show the procedure necessary to initialize a magnetic tape. 
After allocating a drive, the magnetic tape is loaded on the device, and the 
INITIALIZE command writes the label SOURCE on it. Then, the MOUNT 
command mounts the magnetic tape so that files can be written on it. 


$ BACKUP filespec MUAO: ... /MEDIA_FORMAT=NOCOMPACTION- 
_$/REWIND 


This example creates a BACKUP tape with compaction and record blocking 
disabled. 
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Format 


Parameter 


Description 


Creates or initializes queues. You use this command to create queues and to 
assign them names and options. The /BATCH qualifier is required to create a 
batch queue. 


Requires OPER (operator) privilege to create queues and manage (M) 
access to modify queues. 


INITIALIZE/QUEUE queue-name[:] 


queue-name[:] 

Specifies the name of an execution queue or a generic queue. The queue name 
may be a string of 1 to 31 characters. The character string can include any 
uppercase and lowercase letters, digits, the dollar sign ($), and the underscore 
(_), and must include at least one alphabetic character. 


Use the INITIALIZE/QUEUE command to create a queue or to change the 
options of an existing queue that is stopped. 


Normally you create output and batch queues by entering the necessary 
INITIALIZE/QUEUE commands when you set up your system or VMScluster. 
Later, you can use the INITIALIZE/QUEVE command to create additional queues 
as they are needed. When you create a queue with the INITIALIZE/QUEUE 
command, information about the queue is stored in the queue database. 


To create and start the queue at the same time, you can use the INITIALIZE 
/QUEUE/START command. If you want to create the queue only and start it at 
another time, you can enter only the INITIALIZE/QUEUE command. Later you 
can enter the START/QUEUE command to begin queue operations. 


You can use the INITIALIZE/QUEUE, START/QUEUE, and SET QUEUE 
commands to change queue options; as you change queue options, information 
about the queue in the queue database is updated. 


You can use the INITIALIZE and START commands only on stopped queues. To 
change options on a running queue, use the SET QUEUE command. To change 
queue options that cannot be altered with the SET QUEUE command, use the 
following procedure: 


1. Stop the queue with the STOP/QUEUE/NEXT command. 


2. Restart the queue with the START/QUEUE or the INITIALIZE/QUEUE 
/START command, specifying the appropriate qualifiers for the options you 
desire. 


Any qualifiers that you do not specify remain as they were when the queue 
was previously initialized, started, or set. 


DCLI-263 


INITIALIZE/QUEUE 


DCLI-264 


Note that initializing an existing queue does not delete any current jobs in that 
queue. Any new queue settings established by the new INITIALIZE/QUEUE 
command affect all jobs waiting in the queue or subsequently entering the queue. 
Any jobs that are executing in the queue when it is stopped complete their 
execution under the old settings. 


The following qualifiers apply to generic and execution queues: 


/OWNER_UIC 
/PROTECTION 
/[NOJRETAIN 
/[NOISTART 
/NAME_OF_MANAGER 


The following qualifiers apply to all types of execution queues: 


/AUTOSTART_ON 
/BASE_PRIORITY 
/[INOJCHARACTERISTICS 
/[NOJENABLE_GENERIC 
/ON 

/WSDEFAULT 
/WSEXTENT 

/WSQUOTA 


The following qualifiers apply only to batch execution queues: 


/CPUDEFAULT 
/CPUMAXIMUM 
/[INOJDISABLE_SWAPPING 
/JOB_LIMIT 


The following qualifiers apply only to printer, terminal, or server execution 
queues: 


/[INOJBLOCK_LIMIT 
/[INO]DEFAULT 
/FORM_MOUNTED 
/[NO]JLIBRARY 
/[INO]JPROCESSOR 
/[NOJRECORD_BLOCKING 
/[NO]SEPARATE 


Types of Queues 


There are several different types of queues. In general, queues can be divided 
into two major classes: generic and execution. When a job is sent to an execution 
queue, it is executed in that queue. No processing takes place in generic queues. 
Generic queues hold jobs that will execute on an execution queue. 


Generic Queues The following are several types of generic queues: 
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¢ Generic batch queue—Holds batch jobs for execution on batch execution 
queues. 


¢ Generic output queue—Holds jobs for execution on output queues. There are 
three types of generic output queues: 


— Generic printer queue—Holds print jobs for printing on output execution 
queues. 


— Generic server queue—Holds jobs for processing on output execution 
queues. 


— Generic terminal queue—Holds print jobs for printing on output execution 
queues. 


The /GENERIC qualifier designates a queue as a generic queue. You specify the 
execution queues to which a generic queue feeds jobs in one of two ways: 


e You can explicitly name execution queues assigned to the generic queue by 
including a list of queues with the /GENERIC qualifier. 


e ‘You can specify the execution queues that may receive jobs from any 
generic queue that does not specify an explicit target list by specifying the 
/ENABLE=GENERIC qualifier when you create the execution queue. 


Generic queues, unlike execution queues, are not automatically stopped when the 
system is shut down or the queue manager is stopped. Therefore, generic queues 
do not normally need to be restarted each time the system reboots. 


Logical Queues 

Another type of queue is the logical queue. A logical queue is a special type of 
generic queue that can place work only into the execution queue specified in the 
ASSIGN/QUEUE command. The logical queue’s relation to an execution queue 
remains in effect until you enter a DEASSIGN/QUEUE command to negate the 
assignment. 


Execution Queues The following are several types of execution queues: 
¢ Batch execution queue—Executes batch jobs.) 


¢ Output execution queue—Processes print output jobs. There are three types 
of output execution queues: 


— Printer execution queue—Invokes a symbiont to process print jobs for a 
printer. 


— Server execution queue—Invokes a customer-written symbiont to process 
jobs. 


— Terminal execution queue—Invokes a symbiont to process print jobs for a 
terminal printer. 


Batch execution queues execute batch jobs. Batch jobs request the execution of 
one or more command procedures in a batch process. 


Output execution queues process print jobs. A print job requests the processing of 
one or more files by a symbiont executing in a symbiont process. The default 
system symbiont is designed to print files on hardcopy devices (printers or 
terminals). Customer-written symbionts can be designed for this or any other 
file processing activity. Server queues process jobs using the server symbiont 
specified with the (PROCESSOR qualifier. Server queue symbionts are written by 
the customer. 
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Hither the /AUTOSTART_ON qualifier or the /ON qualifier designates a queue as 
an execution queue, and specifies where the queue is to run. 


By using the /ON qualifier, you can specify one node (for batch queues) or node 
and device (for output queues) on which the queue can be started. A queue 
initialized with the /ON qualifier needs to be started by a command explicitly 
naming the queue. 


You can specify one or more nodes (or nodes and devices) on which the queue can 
be started by using the /AUTOSTART_ON qualifier. A queue initialized with the 
/AUTOSTART_ON qualifier is automatically started by the queue manager when 
any of the queue’s nodes have been enabled for autostart by that queue manager. 


Autostart Queues An execution queue (either batch or output) can be designated 
as an autostart queue. Because all of a queue manager’s autostart queues on a 
node can be started with a single command, autostart queues eliminate the need 
for lengthy queue startup procedures. 


In a VMScluster, autostart queues can be set up to run on one of several nodes. 
If a queue is set up this way, and the node on which the queue is running leaves 
the cluster, the queue can fail over to another node and remain available to the 
cluster. 


The /AUTOSTART_ON qualifier designates an execution queue as an autostart 
queue. 


/AUTOSTART_ON=(node::[device][,...]) 

Designates the queue as an autostart execution queue and specifies the node, or 
node and device, on which the queue can be located. For batch queues, only node 
is applicable. 


In a cluster, you can specify more than one node (or node and device) on which 

a queue can run, in the preferred order in which nodes should claim the queue. 
This allows the queue to fail over to another node if the node on which the queue 
is running leaves the cluster. 


When you enter the INITIALIZE/QUEUE command with the /AUTOSTART_ON 
qualifier, you must initially activate the queue for autostart, either by specifying 
the /START qualifier with the INITIALIZE/QUEUE command or by entering a 
START/QUEUE command. However, the queue will not begin processing jobs 
until the ENABLE AUTOSTART/QUEUES command is entered for a node on 
which the queue can run. 


This qualifier cannot be used in conjunction with the /ON or /GENERIC qualifier. 
However, if you are reinitializing an existing queue, you can specify the 
/AUTOSTART_ON qualifier for a queue previously created or started with 

the /ON qualifier. Doing so overrides the /ON qualifier and makes the queue an 
autostart queue. 


For more information about autostart queues, see the chapter about queues in 
OpenVMS System Manager’s Manual: Essentials. 


/BASE_PRIORITY=n 
Specifies the base process priority at which jobs are initiated from a batch 
execution queue. By default, if you omit the qualifier, jobs are initiated at the 
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same priority as the base priority established by DEFPRI at system generation 
(usually 4). The base priority specifier can be any decimal value from 0 to 15. 


You also can specify this qualifier for an output execution queue. In this context 
the /BASE_PRIORITY qualifier establishes the base priority of the symbiont 
process when the symbiont process is created. 


/BATCH 

/NOBATCH (default) 

Specifies that you are initializing a batch queue. If you are reinitializing an 
existing queue, you can use the /BATCH qualifier only if the queue was created 
as a batch queue. . 


A batch queue is classified as either an execution queue or a generic queue. By 
default, the /BATCH qualifier initializes an execution queue. To specify a generic 
batch queue, use the (GENERIC qualifier together with the /BATCH qualifier. 


The /BATCH and /DEVICE qualifiers are mutually exclusive; the /(NOBATCH and 
/NODEVICE qualifiers cannot be used together. 


/BLOCK_LIMIT=([lowlim, Juplim) 

/NOBLOCK_LIMIT (default) 

Limits the size of print jobs that can be processed on an output execution queue. 
The /BLOCK_LIMIT qualifier allows you to reserve certain printers for certain 
size jobs. You must specify at least one of the parameters. 


The lowlim parameter is a decimal number referring to the minimum number 
of blocks accepted by the queue for a print job. If a print job is submitted that 
contains fewer blocks than the Jowlim value, the job remains pending until 
the block limit for the queue is changed. After the block limit for the queue is 
decreased sufficiently, the job is processed. 


The uplim parameter is a decimal number referring to the maximum number 
of blocks that the queue accepts for a print job. If a print job is submitted that 
exceeds this value, the job remains pending until the block limit for the queue is 
changed. After the block limit for the queue is increased sufficiently, the job is 
processed. 


If you specify only an upper limit for jobs, you can omit the parentheses. For 
example, /BLOCK_LIMIT=1000 means that only jobs with 1000 blocks or less 
are processed in the queue. To specify only a lower job limit, you must use a null 
string ("") to indicate the upper specifier. For example, /BLOCK_LIMIT=(500,"") 
means any job with 500 or more blocks is processed in the queue. You can specify 
both a lower and upper limit. For example, /BLOCK_LIMIT=(200,2000) means 
that jobs with less than 200 blocks or more than 2000 blocks are not processed in 
the queue. 


The /NOBLOCK_LIMIT qualifier cancels the previous setting established by the 
/BLOCK_LIMIT qualifier for that queue. 


/CHARACTERISTICS=(characteristic[,...]) 

/NOCHARACTERISTICS (default) 

Specifies one or more characteristics for processing jobs on an execution queue. 
If you specify only one characteristic, you can omit the parentheses. If a queue 
does not have all the characteristics that have been specified for a job, the job 
remains pending. Each time you specify the /CHARACTERISTICS qualifier, all 
previously set characteristics are cancelled. Only the characteristics specified 
with the qualifier are established for the queue. 
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Queue characteristics are installation specific. The characteristic parameter can 
be either a value from 0 to 127 or a characteristic name that has been defined by 
the DEFINE/CHARACTERISTIC command. 


The /NOCHARACTERISTICS qualifier cancels any settings previously 
established by the (CHARACTERISTICS qualifier for that queue. 


ICLOSE 

Prevents jobs from being entered in the queue through PRINT or SUBMIT 
commands or as a result of requeue operations. To allow jobs to be entered, 
use the /OPEN qualifier. Whether a queue accepts or rejects new job entries-is 
independent of the queue’s state (such as paused, stopped, or stalled). When a 
queue is marked closed, jobs executing continue to execute. Jobs pending in the 
queue continue to be candidates for execution. 


/CPUDEFAULT=time 

Defines the default CPU time limit for all jobs in this batch execution queue. You 
can specify time as delta time, 0, INFINITE, or NONE (default). You can specify 
up to 497 days of delta time. 


If the queue does not have a specified CPUMAXIMUM time limit and the 
value established in the user authorization file (UAF) has a specified CPU time 
limit of NONE, either the value 0 or the keyword INFINITE allows unlimited 
CPU time. If you specify NONE, the CPU time value defaults to the value 
specified either in the UAF or by the SUBMIT command (if included). CPU time 
values must be greater than or equal to the number specified by the system 
parameter PQL_MCPULM. The time cannot exceed the CPU time limit set by 
the /CPUMAXIMUM qualifier. For information on specifying delta time, see the 
OpenVMS User’s Manual. For more information on specifying CPU time limits, 
see Table DCLI-1. 


/CPUMAXIMUM=time 

Defines the maximum CPU time limit for all jobs in a batch execution queue. You 
can specify time as delta time, 0, INFINITE, or NONE (default). You can specify 
up to 497 days of delta time. 


The /CPUMAXIMUM qualifier overrides the time limit specified in the user 
authorization file (UAF) for any user submitting a job to the queue. Either the 
value 0 or the keyword INFINITE allows unlimited CPU time. If you specify 
NONE, the CPU time value defaults to the value specified either in the UAF or 
by the SUBMIT command (if included). CPU time values must be greater than or 
equal to the number specified by the system parameter PQL_MCPULM. 


For information on specifying delta times, see the OpenVMS User’s Manual. For 
more information on specifying CPU time limits, see Table DCLI-1. 


A CPU time limit for processes is specified by each user record in the system 
UAF. You also can specify the following: a default CPU time limit or a maximum 
CPU time limit for all jobs in a given queue, or a default CPU time limit for 
individual jobs in the queue. Table DCLI-1 shows the action taken for each value 
specified and possible combinations of specifications. 
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Table DCLI-1 CPU Time Limit Specifications and Actions 

CPU Time Limit Default CPU Time Maximum CPU Time 

Specified by the Limit Specified for Limit Specified for the 

SUBMIT Command? the Queue? Queue? Action Taken 

No No No Use the UAF value. 

Yes No No Use the smaller of SUBMIT 
command and UAF values. 

Yes Yes No Use the smaller of SUBMIT 
command and UAF values. 

No Yes Use the smaller of SUBMIT 


Yes 


Yes 


command and queue’s 
maximum values. 


Yes Yes Use the smaller of SUBMIT 
command and queue’s 
maximum values. 


Yes Yes Use the smaller of queue’s 
default and maximum values. 

No Yes Use the maximum value. 

Yes No Use the smaller of UAF and 


queue’s default values. 


/DEFAULT=(option{.,...]) 

/NODEFAULT 

Establishes defaults for certain options of the PRINT command. Defaults are 
specified by the list of options. If you specify only one option, you can omit the 
parentheses. After you set an option for the queue with the /DEFAULT qualifier, 
you do not have to specify that option in your PRINT command. If you do specify 
these options in your PRINT command, the values specified with the PRINT 
command override the values established for the queue with the /DEFAULT 
qualifier. 


You cannot use the /DEFAULT qualifier with the /GENERIC qualifier. 
Possible options are as follows: 


[NO]JBURST|[=keyword] Controls whether two file flag pages with 
a burst bar between them are printed 
preceding output. If you specify the value 
ALL (default), these flag pages are printed 
before each file in the job. If you specify the 
value ONE, these flag pages are printed once 
before the first file in the job. 


[NOJFEED Controls whether a form feed is inserted 
automatically at the end of a page. 
[NO]FLAG[=keyword] Controls whether a file flag page is printed 


preceding output. If you specify the value 
ALL (default), a file flag page is printed 
before each file in the job. If you specify the 
value ONE, a file flag page is printed once 
before the first file in the job. 
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FORM=type ' Specifies the default form for an output 
execution queue. If a job is submitted 
without an explicit form definition, this form 
is used to process the job. If no form type is 
explicitly specified with the FORM keyword, 
the system assigns the form DEFAULT to 
the queue. See also the description of the 
/FORM_MOUNTED=type qualifier. 


[NO]JTRAILER[=keyword] Controls whether a file trailer page is 
printed following output. If you specify 
the value ALL (default), a file trailer page 
is printed after each file in the job. If you 
specify the value ONE, a trailer page is 
printed once after the last file in the job. 


When you specify the BURST option for a file, the [NO]JFLAG option does not add 
or subtract a flag page from the two flag pages that are printed preceding the file. 


For information on establishing mandatory queue options, see the description 
of the /SEPARATE qualifier. For more information on specifying default queue 
options, see the chapter on queues in the OpenVMS System Manager’s Manual. 


/DESCRIPTION=string 

/NODESCRIPTION (default) 

Specifies a string of up to 255 characters used to provide operator-supplied 
information about the queue. 


Enclose strings containing lowercase letters, blanks, or other nonalphanumeric 
characters (including spaces) in quotation marks (“”). 


The /NODESCRIPTION qualifier removes any a i Zale text that may be 
associated with the queue. 


/DEVICE[=option] 

/NODEVICE 

Specifies that you are initializing an output queue of a particular type. If you are 
reinitializing an existing queue, you can use the /DEVICE qualifier only if the 
queue was created as an output queue. Possible options are as follows: 


PRINTER Indicates a printer queue. 

SERVER Indicates a server queue. A server queue is controlled by 
the user-modified or user-written symbiont specified with the 
/PROCESSOR qualifier. 

TERMINAL Indicates a terminal queue. 


If you specify the /DEVICE qualifier without a queue type, the 


-/DEVICE=PRINTER qualifier is used by default. 


An output queue is classified as either an execution or generic queue. By default, 
the /DEVICE qualifier initializes an execution queue of the designated type. To 
specify a generic printer, server, or terminal queue, use the /(GENERIC qualifier 
with the /DEVICE qualifier. 


You specify the queue type with the /DEVICE qualifier for informational purposes. 
When an output execution queue is started, the symbiont associated with the 
queue determines the actual queue type. The standard symbiont examines device 
characteristics to establish whether the queue should be marked as printer or 
terminal. By convention, user-modified and user-written symbionts mark the 
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queue as a server queue. The device type of a generic queue need not match the 
device type of its execution queues. 


The /DEVICE and /BATCH qualifiers are mutually exclusive; the /NODEVICE 
and /NOBATCH qualifiers cannot be used together. 


/DISABLE_SWAPPING 

/NODISABLE_SWAPPING (default) 

Controls whether batch jobs executed from a queue can be swapped in and out of 
memory. 


/ENABLE_GENERIC (default) 

/NOENABLE_GENERIC 

Specifies whether files queued to a generic queue that does not specify explicit 
queue names with the /GENERIC qualifier can be placed in this execution queue 
for processing. For more information, see the description of the /GENERIC 
qualifier. 


/FORM_MOUNTED=type 
Specifies the mounted form for an output execution queue. 


If no form type is explicitly specified, the system assigns the form DEFAULT to 
the queue. 


If the stock of the mounted form does not match the stock of the default form, 
as indicated by the /DEFAULT=FORM qualifier, all jobs submitted to this queue 
without an explicit form definition enter a pending state and remains pending 
until the stock of the mounted form of the queue is identical to the stock of the 
form associated with the job. 


If a job is submitted with an explicit form and the stock of the explicit form is 
not identical to the stock of the mounted form, the job enters a pending state and 
remains pending until the stock of the mounted form of the queue is identical to 
the stock of the form associated with the job. 


To specify the form type, use either a numeric value or a form name that has been 
defined by the DEFINE/FORM command. Form types are installation-specific. 
You cannot use the /FORM_MOUNTED qualifier with the /GENERIC qualifier. 


/GENERIC[=(queue-name]....])] 

/NOGENERIC (default) 

Specifies a generic queue. Also specifies that jobs placed in this queue can 

be moved for processing to compatible execution queues. The /GENERIC 
qualifier optionally accepts a list of target execution queues that have been 
previously defined. For a generic batch queue, these target queues must be 
batch execution queues. For a generic output queue, these target queues must 
be output execution queues, but can be of any type (printer, server, or terminal). 
For example, a generic printer queue can feed a mixture of printer and terminal 
execution queues. 


If you do not specify any target execution queues with the /GENERIC qualifier, 
jobs can be moved to any execution queue that (1) is initialized with the 
/ENABLE_GENERIC qualifier, and (2) is the same type (batch or output) as the 
generic queue. 


To define the queue as a generic batch or output queue, you use the /(GENERIC 
qualifier with either the /BATCH or the /DEVICE qualifier. If you specify neither 
/BATCH nor /DEVICE on creation of a generic queue, the queue becomes a 
generic printer queue by default. 
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You cannot use the /SEPARATE qualifier with the /GENERIC qualifier. 


/JOB_LIMIT=n 

Indicates the number of batch jobs that can be executed concurrently from the 
queue. Specify a number in the range 1 to 255. The job limit default value for n 
is 1. 


/LIBRARY=filename 

/NOLIBRARY 

Specifies the file name for the device control library. When you initialize 

an output execution queue, you can use the /LIBRARY qualifier to 

specify an alternate device control library. The default library is 
SYS$LIBRARY:SYSDEVCTL.TLB. You can use only a file name as the parameter 
of the /LIBRARY qualifier. The system always assumes that the file is located in 
SYS$LIBRARY and that the file type is TLB. 


/NAME_OF_MANAGER=name . 
Identifies the name of the queue manager to control the queue. Once the queue 
is created, the queue manager assignment may not be altered. 


If the /NAME_OF_ MANAGER qualifier is omitted, then the default name 
SYS$QUEUE_MANAGER is used. 


If the INITIALIZE/QUEUVE command is used to modify a queue, and that queue 
is not controlled by the default queue manager, then the name of the controlling 
queue manager should be specified with /NAME_OF_MANAGER qualifier. 
Alternately, the logical name SYS$QUEUE_MANAGER can be defined to be the 
correct queue manager, making that queue manager the default for the current 
process. 


/ON=[node::]device[:] (printer, terminal, server queue) 

/ON=node:: (batch queue) 

Specifies the node or device, or both, on which this execution queue is located. 
For batch execution queues, you can specify only the node name. For output 
execution queues, you can include both the node name and the device name. By 
default, a queue executes on the same node from which you start the queue. The 
default device parameter is the same as the queue name. 


The node name is used in VAXcluster systems; it must match the node name 
specified by the system parameter SCSNODE for the VAX computer on which the 
queue executes. 


You cannot use the /ON qualifier with the /AUTOSTART_ON or /GENERIC 
qualifier. However, if you are reinitializing an existing queue, you can specify the 
/ON qualifier for a queue previously created or started with the /AUTOSTART_ 
ON qualifier. Doing so overrides the /AUTOSTART_ON option and makes the 
queue a nonautostart queue. | 


/OPEN (default) 

Allows jobs to be entered in the queue through PRINT or SUBMIT commands 
or as the result of requeue operations. To prevent jobs from being entered in the 
queue, use the /CLOSE qualifier. Whether a queue accepts or rejects new job 
entries is independent of the queue’s state (such as paused, stopped, or stalled). 
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/OWNER_U!IC=uic 

Enables you to change the user identification code (UIC) of the queue. Specify 
the UIC by using standard UIC format as described in the OpenVMS Guide to 
‘System Security. The default UIC is [1,4]. 


/PROCESSOR=filename 

/NOPROCESSOR 

Allows you to specify your own print symbiont for an output execution queue. You 
can use any valid file name as a parameter of the /PROCESSOR qualifier. The 
system supplies the device and directory name SYS$SYSTEM and the file type 
EXE. If you use this qualifier for an output queue, it specifies that the symbiont 
image to be executed is SYS$SYSTEM:filename.EXE. 


By default, SYS$SYSTEM:PRTSMB.EXE is the symbiont image associated with 
an output execution queue. 


The /NOPROCESSOR qualifier cancels any previous setting established with the 
/PROCESSOR qualifier and causes SYS$SYSTEM:PRTSMB.EXE to be used. 


/PROTECTION=(ownership[:access].,...) 
Specifies the protection of the queue. 


e Specify the ownership parameter as system (S), owner (O), group (G), or 
world (W). 


e Specify the access parameter as read (R), submit (S), manage (M), or delete 
(D). 


A null access specification means no access. The default protection is 
(SYSTEM:M, OWNER:D, GROUP:R, WORLD:S). If you include only one 
protection code, you can omit the parentheses. For more information on 
specifying protection codes, see the OpenVMS Guide to System Security. For 
more information on controlling queue operations through UIC-based protection, 
see the chapter on queues in the OpenVMS System Manager’s Manual. 


/RECORD_BLOCKING (default) 

/NORECORD_BLOCKING 

Determines whether the symbiont can concatenate (or block together) output 
records for transmission to the output device. If you specify the /NORECORD_ 
BLOCKING qualifier, the symbiont sends each formatted record in a separate I/O 
request to the output device. For the standard OpenVMS print symbiont, record 
blocking can have a significant performance advantage over single-record mode. 


/RETAIN[=option] 

/NORETAIN (default) 

Holds jobs in the queue in a retained state after they have executed. The 
/NORETAIN qualifier enables you to reset the queue to the default. Possible 
options are as follows: 


ALL (default) Holds all jobs in the queue after execution. 
ERROR Holds in the queue only jobs that complete 
unsuccessfully. 


A user can request a job retention option for a job by specifying the /RETAIN 
qualifier with the PRINT, SUBMIT, or SET ENTRY command. However, the 
job retention option you specify for a queue overrides any job retention option 
requested by a user for a job in that queue. 
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/SCHEDULES=SIZE (default) 

/SCHEDULE=NOSIZE 

Specifies whether pending jobs in an output execution queue are scheduled 

for printing based on the size of the job. When the default qualifier 
/SCHEDULESSIZE is in effect, shorter jobs print before longer ones. When 

the /SCHEDULE=NOSIZE qualifier is in effect, jobs are printed in the order they 
were submitted, regardless of size. 


If you enter this command while there are pending jobs in any queue, its effect on 
future jobs is unpredictable. 


/SEPARATE=(option....]) 

/NOSEPARATE (default) 

Specifies the mandatory queue options, or job separation options, for an output 
execution queue. Job separation options cannot be overridden by the PRINT 
command. 


You cannot use the /SEPARATE qualifier with the /GENERIC qualifier. 
The job separation options are as follows: 


[NOJBURST Specifies whether two job flag pages with 
a burst bar between them are printed at 
the beginning of each job. 


[NO]JFLAG | Specifies whether a job flag page is 
printed at the beginning of each job. 

[NO]JTRAILER Specifies whether a job trailer page is 
printed at the end of each job. 

[NOJRESET=(modulef,...]) Specifies one or more device control 


library modules that contain the job 
reset sequence for the queue. The 
specified modules from the queue’s 
device control library (by default 
SYS$LIBRARY:SYSDEVCTL) are used 

to reset the device at the end of each job. 
The RESET sequence occurs after any file 
trailer and before any job trailer. Thus, 
all job separation pages are printed when 
the device is in its RESET state. 


When you specify the /SEPARATE=BURST qualifier, the [NO]FLAG separation 
option does not add or subtract a flag page from the two flag pages that are 
printed preceding the job. 


For information on establishing queue options that can be averioden, see the 
description of the /DEFAULT qualifier. 


For more information on specifying mandatory queue options, see the chapter on 
queues in the OpenVMS System Manager’s Manual. 


/START 
/NOSTART (default) 
Starts the queue being initialized by the current INITIALIZE/QUEUE command. 


For autostart queues, this qualifier activates the queue for autostart. The queue 
begins processing jobs when autostart is enabled with the ENABLE AUTOSTART 
/QUEUES command on any node on which the queue can run. 


INITIALIZE/QUEUE 


/WSDEFAULT=n 
Defines for a batch job a working set default, the default number of physical 
pages that the job can use. 


The value set by this qualifier overrides the value defined in the user 
authorization file (UAF) of any user submitting a job to the queue. 


Specify the value of n as a number of 512-byte pagelets on Alpha systems or 
512-byte pages on VAX. Note that OpenVMS rounds up this value to the nearest 
CPU-specific page so that actual amount of physical memory allowed may be 
larger than the specified amount on Alpha. For further information, see the 
OpenVMS System Manager’s Manual. 


If you specify 0 or NONE, the working set default value defaults to the value 
specified in the UAF or by the SUBMIT command (if it includes a WSDEFAULT 
value). 


You also can specify this qualifier for an output execution queue. Used in this 
context, the /(WSDEFAULT qualifier establishes the working set default of the 
symbiont process for an output execution queue when the symbiont process is 
created. 


For more information about the way a working set default affects batch jobs, see 
Table DCLI-2. 


/WSEXTENT=n 

Defines for the batch job a working set extent, the maximum amount of physical 
memory that the job can use. The job only uses the maximum amount of physical 
memory when the system has excess free pages. The value set by this qualifier 
overrides the value defined in the user authorization file (UAF) of any user 
submitting a job to the queue. 


Specify the value of n as a number of 512-byte pagelets on Alpha or and 512-byte 
pages on VAX. Note that OpenVMS rounds up this value to the nearest CPU- 
specific page so that actual amount of physical memory allowed may be larger 
than the specified amount on Alpha. 


If you specify 0 or NONE, the working set extent value defaults to the value 
specified in the UAF or by the SUBMIT command (if it includes a WSEXTENT 
value). 


You also can specify this qualifier for an output execution queue. Used in this 
context, the /WSEXTENT qualifier establishes the working set extent of the 
symbiont process for an output execution queue when the symbiont process is 
created. 


For more information about the way a working set extent affects batch jobs, see 
Table DCLI-2. 


/WSQUOTA=n 
Defines for a batch job a working set quota, the amount of physical memory that 
is guaranteed to the job. 


The value set by this qualifier overrides the value defined in the user 
authorization file (UAF) of any user submitting a job to the queue. 


Specify the value of n as a number of 512-byte pagelets on OpenVMS Alpha or 
512-byte pages on OpenVMS VAX. OpenVMS rounds up this value to the nearest 
CPU-specific page so that actual amount of physical memory allowed may be 
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larger than the specified amount on OpenVMS Alpha. For further information, 
see the OpenVMS System Manager’s Manual. 


If you specify 0 or NONE, the working set quota value defaults to the value 
specified in the UAF or by the SUBMIT command (if it includes a WSQUOTA 
value). 


You also can specify this qualifier for an output execution queue. Used in this 
context, the /WSQUOTA qualifier establishes the working set quota of the 
symbiont process for an output execution queue when the symbiont process is 
created. 


Working set default, working set quota, and working set extent values are 
included in each user record in the system UAF. You can specify working set 
values for individual jobs or for all jobs in a given queue. The decision table 


(Table DCLI-2) shows the action taken for different combinations of specifications 


that involve working set values. 


Table DCLI-2 Working Set Default, Extent, and Quota Decision 


Is the SUBMIT command Is the queue value 

value specified? specified? Action taken 

No No Use the UAF value. 

No Yes Use value for the queue. 

Yes Yes Use smaller of the two 
values. 

Yes No Compare specified value 
with UAF value; use the 
smaller. 


1. $ INITIALIZE/QUEUE/BATCH/START - 
_$ /AUTOSTART ON=(DATA::, WARF::, DEANNA::) BATCH 1 


The INITIALIZE/QUEUE command in this example creates the batch queue 
BATCH_1, and designates it as an autostart queue capable of executing on 
node DATA, WARF, or DEANNA. The /START qualifier activates the queue 
for autostart. The queue will begin executing on the first node (in the list of 
nodes specified) for which the ENABLE AUTOSTART/QUEUES command is 
entered. 


If the node on which BATCH_1 is executing is taken out of the VMScluster, 
the queue will be stopped on that node and will fail over to the first available 


node in the node list on which autostart is enabled for a queue manager 
SYS$QUEUE_MANAGER. 


As long as autostart is enabled on one of the nodes in the list, this queue 
will be started and available to execute batch jobs. If all three nodes in the 
example are shut down or if autostart is disabled, the queue will remain 
stopped until one of the three nodes in the node list joins the cluster and 
executes the ENABLE AUTOSTART/QUEUES command. 


The ENABLE AUTOSTART/QUEUES and INITIALIZE/QUEUE commands 
affect only the queues managed by the default queue manager SYS$QUEUE_ 
MANAGER because the /NAME_OF_MANAGER qualifier is not specified. 


2. 


INITIALIZE/QUEUVE 


$ INITIALIZE/QUEUE/START/BATCH/JOB LIMIT=3 SYS$BATCH 
$ INITIALIZE/QUEUE/START/BATCH/JOB LIMIT=1/WSEXTENT=2000 BIG BATCH 


In this example, the first INITIALIZE/QUEUE command creates a batch 
queue called SYS$BATCH that can be used for any batch job. The 
/JOB_LIMIT qualifier allows three jobs to execute concurrently. The 
second INITIALIZE/QUEUE command creates a second batch queue called 


. BIG_BATCH that is designed for large jobs. Only one job can execute at a 


time. The working set extent can be as high as 125 pages on OpenVMS Alpha 
(on a system with 8KB pages) or 2000 pages on OpenVMS VAX. 


$ INITIALIZE/QUEUE/START/DEFAULT= (FLAG, TRAILER=ONE) - 

$ /ON=LPAQ: LPAO_PRINT 

$ INITIALIZE/QUEUE/START/DEFAULT=(FLAG, TRAILER=ONE) - 

_$ /BLOCK_LIMIT=(1000,"")/ON=LPBO: LPBO PRINT 

$ INITIALIZE/QUEUE/START/GENERIC=(LPAQ_ PRINT,LPBO PRINT) SYS$PRINT 
$ INITIALIZE/QUEUE/START/FORM MOUNTED=LETTER- = 

_$ /BLOCK_LIMIT=50/ON=TXA5: LOP 


In this example, the first three INITIALIZE/QUEUE commands set up 
printer queues. Both queue LPAO_ PRINT and LPBO_PRINT are set up to 
put a flag page before each file within a job and a trailer page after only 
the last page in a job. In addition, LPBO_PRINT has a minimum block size 
of 1000. Thus only print jobs larger than 1000 blocks can execute on that 
queue. SYS$PRINT is established as a generic queue that can direct jobs 
to either LPAO_PRINT or LPBO_PRINT. Jobs that are too small to run on 
LPBO_PRINT will be queued from SYS$PRINT to LPAO_PRINT. 


The last INITIALIZE/QUEUE command sets up a terminal queue on TXA5. 
A job queued with a form that has a stock type other than the stock type 

of form LETTER remains pending in the queue until a form with the same 
stock type is mounted on the queue, or until the entry is deleted from the 
queue or moved to another queue. LETTER has been established at this site 
to indicate special letterhead paper. The block size limit is 50, indicating that 
this queue is reserved for jobs smaller than 51 blocks. 
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Reads a value from SYS$COMMAND (usually the terminal in interactive mode 
or the next line in the main command procedure) and assigns it to a symbol. 


INQUIRE symbol-name [prompt-string] 


symbol-name 
Specifies a symbol consisting of 1 to 255 alphanumeric characters. 


prompt-string 

Specifies the prompt to be displayed at the terminal when the INQUIRE 
command is executed. String values are automatically converted to uppercase. 
Also, any leading and trailing spaces and tabs are removed, and multiple spaces 
and tabs between characters are compressed to a single space. 


Enclose the prompt in quotation marks (“ ”) if it contains lowercase characters, 
punctuation, multiple blanks or tabs, or an at sign (@). To denote an actual 
quotation mark in a prompt-string, enclose the entire string in quotation marks 
and use quotation marks (“”) within the string. 


When the system displays the prompt string at the terminal, it generally places 
a colon (:) and a space at the end of the string. (See the /PUNCTUATION 
qualifier.) 


If you do not specify a prompt string, the command interpreter uses the symbol 
name to prompt for a value. 


The INQUIRE command displays the prompting message to and reads the 
response from the input stream established when your process was created. 

This means that when the INQUIRE command is executed in a command 
procedure executed interactively, the prompting message is always displayed on 
the terminal, regardless of the level of nesting of command procedures. Note that 
input to the INQUIRE command in command procedures will be placed in the 
RECALL buffer. 


When you enter a response to the prompt string, the value is assigned as a 
character string to the specified symbol. Lowercase characters are automatically 
converted to uppercase, leading and trailing spaces and tabs are removed, and 
multiple spaces and tabs between characters are compressed to a single space. 
To prohibit conversion to uppercase and retain space and tab characters, place 
quotation marks around the string. 


To use symbols or lexical functions when you enter a response to the prompt 
string, use single quotation marks (‘’) to request symbol substitution. 


Note that you can also use the READ command to obtain data interactively 

from the terminal. The READ command accepts data exactly as the user types 
it; characters are not automatically converted to uppercase and spaces are not 
compressed. However, symbols and lexical functions will not be translated even if 
you use apostrophes to request symbol substitution. 


Qualifiers 


Examples 


INQUIRE 


When an INQUIRE command is entered in a batch job, the command reads 
the response from the next line in the command procedure; if procedures are 
nested, it reads the response from the first level command procedure. If the 
next line in the batch job command procedure begins with a dollar sign ($), the 
line is interpreted as a command, not as a response to the INQUIRE command. 
The INQUIRE command then assigns a null string to the specified symbol, and 
the batch job continues processing with the command on the line following the 
INQUIRE command. 


/GLOBAL 
Specifies that the symbol be placed in the global symbol table. If you do not 
specify the /GLOBAL qualifier, the symbol is placed in the local symbol table. 


/LOCAL (default) 
Specifies that the symbol be placed in the local symbol table for the current 
command procedure. 


/PUNCTUATION (default) 

/NOPUNCTUATION 

Inserts a colon and a space after the prompt when it is displayed on the terminal. 
To suppress the colon and space, specify the /NOPUNCTUATION qualifier. 


1. $ INQUIRE CHECK "Enter Y[ES] to continue" 
$ IF .NOT. CHECK THEN EXIT 


The INQUIRE command displays the following prompting message at the 
terminal: 


Enter Y[ES] to continue: 


The INQUIRE command prompts for a value, which is assigned to the symbol 
CHECK. The IF command tests the value assigned to the symbol CHECK. 

If the value assigned to CHECK is true (that is, an odd numeric value, a 
character string that begins with a T, t, Y, or y, or an odd numeric character 
string), the procedure continues executing. 


If the value assigned to CHECK is false (that is, an even numeric value, a 
character string that begins with any letter except T, t, Y, or y, or an even 
numeric character string), the procedure exits. 


2. $ INQUIRE COUNT 
$ IF COUNT .GT. 10 THEN GOTO SKIP 


$ SKIP: 
The INQUIRE command prompts for a count with the following message: 
COUNT: 


Then the command procedure uses the value of the symbol COUNT to 
determine whether to execute the next sequence of commands or to transfer 
control to the line labeled SKIP. 
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$ IF Pl .EQS. "" THEN INQUIRE Pl "FILE NAME" 
$ FORTRAN ‘Pl’ 


The IF command checks whether a parameter was passed to the command 
procedure by checking if the symbol P1 is null; if it is, it means that no 
parameter was specified, and the INQUIRE command is issued to prompt for 
the parameter. If P1 was specified, the INQUIRE command is not executed, 
and the FORTRAN command compiles the name of the file specified as a 
parameter. 


INSTALL 


Format 


INSTALL 


Invokes the Install utility, which enhances the performance of selected executable 
and shareable images by making them “known” to the system and assigning them 
appropriate attributes. For a complete description of the Install utility, see the 
OpenVMS System Management Utilities Reference Manual. 


INSTALL [subcommand] [filespec] 
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Identifies the beginning of a batch job submitted through a card reader. Each 
batch job submitted through the system card reader must be preceded by a JOB 
card. 


JOB cannot be abbreviated. 
$ JOB user-name 


user-name 
Identifies the user name under which the job is to be run. Specify the user name 
as you would during the login procedure. 


The JOB card identifies the user submitting the job and is followed by a 
PASSWORD card giving the password. (Although the PASSWORD card is 
required, you do not have to use a password on the card if the account has a null 
password.) 


The user name and password are validated by the system authorization file in 
the same manner as they are validated in the login procedure. The process that 
executes the batch job is assigned the disk and directory defaults and privileges 
associated with the user account. If a LOGIN.COM file exists for the specified 
user name, it is executed at the start of the job. 


The end of a batch job is signaled by the EOJ command, by an EOF card 
(12-11-0-1-6-7-8-9 overpunch), or by another JOB card. 


/AFTER=time 
Holds the job until the specified time. If the specified time has already passed, 
the job is queued for immediate processing. 


The time can be specified as either absolute time or a combination of absolute 
and delta times. For complete information on specifying time values, see the 
OpenVMS User’s Manual. 


/CHARACTERISTICS=(characteristic[,...]) 

Specifies one or more characteristics required for processing the job. If you specify 
only one characteristic, you can omit the parentheses. Codes for characteristics 
are installation-defined. Use the SHOW QUEUE/CHARACTERISTICS command 
to see which characteristics are available on your system. 


All the characteristics specified for the job must also be specified for the queue 
that will execute the job. If not, the job remains pending in the queue until 
the queue characteristics are changed or the entry is deleted with the DELETE 
/ENTRY command. Users need not specify every characteristic of a queue 
with the JOB command as long as the ones they specify are a subset of the 
characteristics set for that queue. The job also runs if no characteristics are 
specified. 


JOB 


/CLl=filename . 

Specifies a different command language interpreter (CLI) with which 

to process the job. The filename parameter specifies that the CLI be 
SYS$SYSTEM:filename.EXE. The default CLI is that defined in the user 
authorization file (UAF). 


/CPUTIME=n 

Specifies a CPU time limit for the batch job. Time can be specified as delta time, 
0, NONE, or INFINITE. (For information on specifying time values, see the 
OpenVMS User’s Manual.) 


When you need less CPU time than authorized, use the /CPUTIME qualifier to 

~ override the base queue value established by the system manager or the value 
authorized in your UAF. Specify 0 or INFINITE to request an infinite amount of 
time. Specify NONE when you want the CPU time to default to your UAF value 
or the limit specified on the queue. Note that you cannot request more time than 
permitted by the base queue limits or your UAF. 


/DELETE (default) 

/NODELETE 

Controls whether the batch input file is deleted after the job is processed. If you 
specify the /NODELETE qualifier, the file is saved in the user’s default directory 
under the default name INPBATCH.COM. If you specify the /NAME qualifier, the 
file name of the batch input file is the same as the job name you supply with the 
/NAME qualifier. 


/HOLD 
/NOHOLD (default) 
Controls whether or not the job is to be made available for immediate processing. 


If you specify the /HOLD qualifier, the job is not released for processing until you 
specifically release it with the /(NOHOLD or the /RELEASE qualifier of the SET 
QUEUE/ENTRY command. 


/KEEP 

/NOKEEP (default) 

Controls whether the log file is deleted after it is printed. The /NOKEEP qualifier 
is the default unless you specify the /(NOPRINTER qualifier. 


/LOG_FILE=filespec 

/NOLOG_FILE 

Controls whether a log file with the specified name is created for the job or 
whether a log file is created. 


When you use the /LOG_FILE qualifier, the system writes the log file to the file 
you specify. If you use the /NOLOG_FILE qualifier, no log file is created. If you 
specify neither form of the qualifier, the log file is written to a file in your default 
directory that has the same file name as the first command file in the job and a 
file type of LOG. Using neither the /LOG_FILE nor the /NOLOG_FILE qualifier 
is the default. 


You can use the /LOG_FILE qualifier to specify that the log file be written to a 
different device. Logical names that occur in the file specification are translated 
at the time the job is submitted. The process executing the batch job must have 
access to the device on which the log file will reside. 
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If you omit the /LOG_FILE qualifier and specify the /NAME qualifier, the log 
file is written to a file having the same file name as that specified by the /NAME 
qualifier and the file type LOG. 


/NAME=job-name 

Specifies a string to be used as the job name and as the file name for both 

the batch job log file and the command file. The job name must be 1 to 39 
alphanumeric characters and must be a valid file name. The default log file name 
is INPBATCH.LOG; the default command file name is INPBATCH.COM. 


INOTIFY 

/NONOTIFY (default) 

Controls whether a message is broadcast to any terminal at which you are logged 
in, notifying you when your job completes or aborts. 


/PARAMETERS=(parameter{,...]) 

Specifies 1 to 8 optional parameters that can be passed to the command 
procedure. The parameters define values to be equated to the symbols P1 to P8 
in the batch job. The symbols are local to the specified command procedure. 


If you specify only one parameter, you can omit the parentheses. 


The commas (, ) delimit individual parameters. If the parameter contains any 
spaces, special characters or delimiters, or lowercase characters, enclose it in 
quotation marks (“”). Individual parameters cannot exceed 255 characters. 


/PRINTER=queue-name 

/NOPRINTER 

Controls whether the job log file is queued to the specified queue for printing 
when the job is complete. The default print queue for the log file is SYS$PRINT. 


If you specify the /NOPRINTER qualifier, the /KEEP qualifier is assumed. 


/PRIORITY=n 
Requires OPER (operator) or ALTPRI (alter priority) privilege to raise 
the priority above the value of the system parameter MAXQUEPRI. 


Specifies the job scheduling priority for the specified job. The value of n is an 
integer from 0 to 255, where 0 is the lowest priority and 255 is the highest. 


The default value for the /PRIORITY qualifier is the value of the system 
parameter DEFQUEPRI. No privilege is needed to set the priority lower than the 
MAXQUEPRI value. 


The /PRIORITY qualifier has no effect on the process priority. The queue 
establishes the process priority. 


/QUEUE=queue-name[:] 

Specifies the name of the batch queue in which the job is to be entered. If you do 
not specify the (QUEUE qualifier, the job is placed in the default system batch job 
queue, SYS$BATCH. 


/RESTART 

/NORESTART (default) 

Specifies whether the job restarts after a system failure or a 
STOP/QUEUE/REQUEUE command. 


JOB 


/TRAILING_BLANKS (default) — 

/NOTRAILING_BLANKS 

Controls whether input cards in the card deck are read in card image form 

or input records are truncated at the last nonblank character. By default, the 
system does not remove trailing blanks from records read through the card 
reader. Use the /NOTRAILING_BLANKS qualifier to request that input records 
be truncated. 


/WSDEFAULT=n 
Defines a working set default for the batch job; the (WSDEFAULT qualifier 
overrides the working set size specified in the user authorization file (UAF). 


Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte 
pages on VAX. Note that OpenVMS rounds up this value to the nearest CPU- 
specific page so that actual amount of physical memory allowed may be larger 
than the specified amount on Alpha. For further information, see the OpenVMS 
System Manager’s Manual. The value n can be any integer from 1 to 65,535, 0, or 
the keyword NONE. 


Use this qualifier to impose a value lower than the base queue value established 
by the system manager or lower than the value authorized in your UAF. A value 
of 0 or the keyword NONE sets the default value to the value specified either 
in your UAF or by the working set quota established for the queue. You cannot 
request a value higher than your default. 


/WSEXTENT=n 
Defines a working set extent for the batch job; the /(WSEXTENT qualifier 
overrides the working set extent in the UAF. 


Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte 
pages on VAX. Note that OpenVMS rounds up this value to the nearest CPU- 
specific page so that actual amount of physical memory allowed may be larger 
than the specified amount on Alpha. For further information, see the OpenVMS 
System Manager’s Manual. The value n can be any integer from 1 to 65,535, 0, or 
the keyword NONE. 


To impose a lower value, use this qualifier to override the base queue value 
established by the system manager rather than the value authorized in your 
UAF. A value of 0 or the keyword NONE sets the default value either to the value 
specified in the UAF or working set extent established for the queue. You cannot 
request a value higher than your default. 


IWSQUOTA=n 
Defines the maximum working set size (working set quota) for the batch job; the 
/WSQUOTA qualifier overrides the value in the UAF. 


Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte 
pages on VAX. Note that OpenVMS rounds up this value to the nearest CPU- 
specific page so that actual amount of physical memory allowed may be larger 
than the specified amount on Alpha. For further information, see the OpenVMS 
System Manager’s Manual. The value n can be any integer from 1 to 65,535, 0, or 
the keyword NONE. 


Use this qualifier to impose a value lower than the base queue value established 
by the system manager or lower than the value authorized in your UAF. Specify 
0 or NONE if you want the working set quota defaulted to either your UAF value 
or the working set quota specified on the queue. You cannot request a value 
higher than your default. 
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$ PRINT AVERAGE 
... Input Data... 


$ RUN AVERAGE 
$ LINK AVERAGE 







...9ource Statements... 
$ FORTRAN SYS$INPUT:AVERAGE 
$ ON WARNING THEN EXIT 
$ PASSWORD HENRY 
$ JOB HIGGINS 
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The JOB and PASSWORD cards identify and authorize the user HIGGINS 
to enter batch jobs. The command stream consists of a FORTRAN command 
and FORTRAN source statements to be compiled. The file name AVERAGE 
following the device name SYS$INPUT provides the compiler with a file 
name for the object and listing files. The output files are cataloged in user 
HIGGINS’s default directory. 


If the compilation is successful, the LINK command creates an executable 
image and the RUN command executes it. Input for the program follows the 
RUN command in the command stream. The last command in the job prints 
the program listing. The last card in the deck contains the EOJ (end of job) 
command. 
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...Command Input... 
$ PASSWORD HENRY 
/PARAMETERS = (A, TEST) 
$ JOB HIGGINS/NAME = BATCH1-— 
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The /NAME qualifier on the JOB card specifies a name for the batch job. 
When the job completes, the printed log file is identified as BATCH1.LOG. 
The JOB command is continued onto a second card with the continuation 
character (-). The /PARAMETERS qualifier defines P1 as A and P2 as TEST. 
The last card in the deck contains the EOJ (end of job) command. 
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A set of functions that return information about character strings and attributes 
of the current process. 


The command language includes constructs, called lexical functions, that 
return information about the current process and about arithmetic and string 
expressions. The functions are called lexical functions because the command 
interpreter evaluates them during the command input scanning (or lexical 
processing) phase of command processing. 


You can use lexical functions in any context in which you normally use symbols 
or expressions. In command procedures, you can use lexical functions to translate 
logical names, to perform character string manipulations, and to determine the 
current processing mode of the procedure. 


The general format of a lexical function is as follows: 


F$function-name([args....]) 


where: 

F$ Indicates that what follows is a lexical function. 

function-name A keyword specifying the function to be evaluated. 
Function names can be truncated to any unique 
abbreviation. 

() Enclose function arguments, if any. The parentheses are 
required for all functions, including functions that do not 
accept any arguments. 

args... | Specify arguments for the function, if any, using integer 


or character string expressions. 
For more information on specifying expressions, see the OpenVMS User’s Manual. 


Table DCLI-—3 lists each lexical function and briefly describes the information 


_ that each function returns. A detailed description of each function, including 


examples, is given in the following pages. 


Table DCLI-3 Summary of Lexical Functions 


Function Description 

F$CONTEXT Specifies selection criteria for use with the F$PID 
function. 

F$CSID Returns a VMScluster identification number 


and updates the context symbol to point to the 
current position in the system’s cluster node list. 


(continued on next page) 
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Function 


F$CVSI 


F$CVTIME 


F$CVUI 


F$DEVICE 
F$DIRECTORY 
F$EDIT 
FSELEMENT 
FSENVIRONMENT 
FSEXTRACT 


F$FAO 


F$FILE_ATTRIBUTES 
F$GETDVI 


FEGETJPI 


F$GETQUI 


F$GETSYI 


F$IDENTIFIER 


+VAX specific 


Description 


Extracts bit fields from character string data 
and converts the result, as a signed value, to an 
integer. 

Retrieves information about an absolute, 
combination, or delta time string. 


Extracts bit fields from character string data and 


converts the result, as an unsigned value, to an 
integer. 

Returns device names of all devices on a system 
that meet the specified selection criteria. 


Returns the current default directory name 
string. 

Edits a character string based on the edits 
specified. 


Extracts an element from a string in which the 
elements are separated by a specified delimiter. 


Obtains information about the DCL command 
environment. 


Extracts a substring from a character string 
expression. 


Invokes the $FAO system service to convert the 
specified control string to a formatted ASCII 
output string. 

Returns attribute information for a specified file. 


Invokes the $GETDVI system service to return 
a specified item of information for a specified 
device. 


Invokes the $GETJPI system service to return 
accounting, status, and identification information 
for a process. 


Invokes the $GETQUI system service to return 
information about queues, batch and print jobs 
currently in those queues, form definitions, 

and characteristic definitions kept in the queue 
database. 

+On VAX, also returns information about a queue 
manager. 


Invokes the $GETSYI system service to return 
status and identification information about the 
local system, or about a node in the local cluster, 
if your system is part of a cluster. 

Converts an identifier in named format to its 
integer equivalent, or vice versa. 


(continued on next page) 
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Table DCLI-3 (Cont.) Summary of Lexical Functions 


Function 
F$INTEGER 


FSLENGTH 
F$LOCATE 


F$MESSAGE 


FSMODE 
F$PARSE 


F$PID 
F$PRIVILEGE 


F$PROCESS 
F$SSEARCH 


F$SETPRV 


F$STRING 
F$TIME 
F$TRNLNM 
F$TYPE 
FSUSER 


F$VERIFY 


Description 


Returns the integer equivalent of the result of 
the specified expression. 

Returns the length of a specified string. 

Locates a character or character substring within 
a string and returns its offset within the string. 
Returns the message text associated with a 
specified system status code value. 

Shows the mode in which a process is executing. 
Invokes the $PARSE RMS service to parse a file 
specification and return either the expanded file 
specification or the particular file specification 
field that you request. 

For each invocation, returns the next process 
identification number in sequence. 

Returns a value of TRUE or FALSE depending 
on whether your current process privileges match 
the privileges listed in the argument. 


‘Returns the current process name string. 


Invokes the $SEARCH RMS service to search 
a directory file, and returns the full file 
specification for a file you name. 


Sets the specified privileges and returns a list of 
keywords indicating the previous state of these 
privileges for the current process. 


Returns the string equivalent of the result of the 
specified expression. 


Returns the current date and time of day, in the 
format dd-mmm-yyyy hh:mm:ss.cc. 


Translates a logical name and returns the 
equivalence name string or the requested 
attributes of the logical name. 


Determines the data type of a symbol. 


Returns the current user identification code 
(UIC). 


Returns the integer 1 if command procedure 
verification is set on; returns the integer 0 if 
command procedure verification is set off. The 
F$VERIFY function also can set new verification 
states. 


Lexical Functions 


FSCONTEXT 


Format 


Specifies selection criteria for use with the F$PID function. The FSCONTEXT 
function enables the F$PID function to obtain information about processes from 
any node in a VMScluster system. 


FECONTEXT(context-type, context-symbol, selection-item, selection-value, 
value-qualifier) 


Return Value 


Arguments 


A null string (""). 


context-type 
Specifies the type of context to be built. At present, the only context type 
available is PROCESS, which is used in constructing selection criteria for F$PID. 


context-symbol 

Specifies a symbol that DCL uses to refer to the context memory being 
constructed by the FSCONTEXT function. The function F$PID uses this context 
symbol to process the appropriate list of process identification (PID) numbers. 


Specify the context symbol by using a symbol. The first time you use the 
F$CONTEXT function in a command procedure, use a symbol that is either 
undefined or equated to the null string. The symbol created will be a local symbol 
of type “PROCESS_CONTEXT”. When the context is no longer valid—that is, 
when all PIDs have been retrieved by calls to the F$PID function or an error 
occurs during one of these calls—the symbol no longer has a type of “PROCESS_ 
CONTEXT”. Then you can use the F$TYPE function in the command procedure 
to find out if it is necessary to cancel the context. 


After setting up the selection criteria, use this context symbol when calling 
F$PID. 


selection-item 
Specifies a keyword that tells FSCONTEXT which selection criterion to use. Use 
only one selection-item keyword per call to FSCONTEXT. 


Note 


Do not use the NEQ selection value on a list of items because it causes 
the condition to always be true. 


For example: 
$ EXAMPLE=f$context( "PROCESS" ,CTX, "USERNAME", "A*,B*","NEQ") 


This equation is parsed as “if the user name is not equal to A* or the 
user name is not equal to B*, then return the process of the users that 
meet the criteria.” Because the operand is a logical or, the conditions 
will always be true (any name will be found to be not equal to A* or B*; 
ALFRED will not be equal to B*; BOB will not be equal to A*). 
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The following table shows valid selection-item keywords for the PROCESS context 


type: 


Selection Item 
ACCOUNT 


AUTHPRI 


CANCEL 


CURPRIV 


GRP 


HW_MODEL 
HW_NAME 


JOBPRCCNT 


JOBTYPE 


MASTER_PID 
MEM 


MODE 


NODE_CSID 


Selection 
Value 


String 


Integer 


Keyword 


Integer 


Integer 
String 


Integer 


Keyword 


String 
Integer 


Keyword 


Integer 


Value 
Qualifiers 


EQL, NEQ 


GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 


ALL, ANY, 
EQL, NEQ 


GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 
EQL, NEQ 


EQL, NEQ 


GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 


EQL, NEQ 


EQL, NEQ 
GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 
EQL, NEQ 


EQL, NEQ 


Comments 


Valid account name or list of 
names. The asterisk (*) and 

the percent sign (%) wildcard 
characters are allowed. 


On Alpha, valid authorized base 
priority (0-63). On VAX, valid 
authorized base priority (0-31). 
Cancels the selection criteria for 
this context. 


Valid privilege name keyword 
or list of keywords. For more 
information, see the OpenVMS 
Guide to System Security. 


UIC group number. 


Valid hardware model number. 


Valid hardware name or a list of 
keywords. The asterisk (*) and 
the percent sign (%) wildcard 
characters are allowed. 


Subprocess count for entire job. 


Valid job-type keyword. Valid 
keywords are DETACHED, 
NETWORK, BATCH, LOCAL, 
DIALUP, and REMOTE. For more 
information, see the OpenVMS 
User’s Manual. 


PID of master process. 
UIC member number. 


Valid process mode keyword. Valid 
keywords are OTHER, NETWORK, 
BATCH, and INTERACTIVE. 

For more information, see the 
OpenVMS User’s Manual. 


Node’s cluster ID number. 


Selection Item 


NODENAME 


OWNER 
PRCCNT 


PRCNAM 


PRI 


PRIB 


STATE 


STS 


TERMINAL 


UIC 


USERNAME 


selection-value 


Selection 
Value 


String 


String 
Integer 


String 


Integer 


Integer 


Keyword 


Keyword - 


String 


String 


String 


Value 
Qualifiers 


EQL, NEQ 


EQL, NEQ 
GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 
EQL, NEQ 


GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 
GEQ, GTR, 
LEQ, LSS, 
EQL, NEQ 
EQL, NEQ 


EQL, NEQ 


EQL, NEQ 


EQL, NEQ 


EQL, NEQ 


Lexical Functions 
FSCONTEXT 


Comments 


Node name or list of node names. 
The asterisk (*) and the percent 
sign (%) wildcard characters are 
allowed. The default is your local 
node. To request all nodes, use the 
value “*”, 


PID of immediate parent process. 
Subprocess count of process. 


Process name or list of process 
names. The asterisk (*) and 


the percent sign (% ) wildcard 


characters are allowed. 


Process priority level number 
(0-63, on Alpha), (0-31, on VAX). 


Base process priority level number 
(0-63, on Alpha), (0-31, on VAX). 


Valid process state keyword. 

For more information, see the 
description of the $GETJPI service 
in the OpenVMS System Services 
Reference Manual. 


Valid process status keyword. 

For more information, see the 
description of the $GETJPI service 
in the OpenVMS System Services 
Reference Manual. 


Terminal name or list of names. 
The asterisk (*) and the percent 
sign (%) wildcard characters are 
allowed. 


User identification code (UIC) 
identifier (that is, of the form 
“[group,member]”). 


User name or list of user names. 
The asterisk (*) and the percent 
sign (%) wildcard characters are 
allowed. 


Specifies the value of the selection criteria. For example, to process all the 


processes running on node MYVAX, specify “MYV. 


keyword. For example: 


” with the “NODENAME” 


$ X = FSCONTEXT("PROCESS", ctx, "NODENAME", "MYVAX", "EQL") 
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Values that are lists are valid with some selection items. If you specify more than 
one item, separate them with commas (,). The following example specifies a list 
of the nodes MYVAX, HERVAX, and HISVAX: 


$ X=FSCONTEXT( "PROCESS" ,ctx, "NODENAME" , "MYVAX, HERVAX, HISVAX", "EQL" ) 


You can use the asterisk (*) and the percent sign (%) wildcard characters for some 
values. Using wildcard characters for selection items is similar to using wildcard 
characters for file names. 


value-qualifier 


‘Specifies qualifiers for selection values. You must qualify selection values. 


You can qualify a number, for example, by requesting that the selection be based 
on one of the following process values: 


e LSS — less than the value specified in the call to F$PID 

e LEQ — less than or equal to the value specified in the call to F$PID 

¢ GTR — greater than the value specified in the call to F$PID 

¢ GEQ — greater than or equal to the value specified in the call to F$PID 
e EQL — equal to the value specified in the call to F$PID 

¢ NEQ — not equal to the value specified in the call to F$PID 


You can qualify some lists with the ALL, ANY, EQL, or NEQ keywords. Such 
lists are usually masks such as the process s PEMVuOES mask, which consists of the 
set of enabled privileges. 


¢ ALL — requires that all items in the list be true for a process 
¢ ANY — requests that any item in the list be part of the attributes of a process 


¢ EQL — requires the values to match exactly (that is, values not specified 
must not be true of the process) 


¢ NEQ — requires that the value must not match 


When using multiple selection values with a particular selection qualifier, a 
match on any one of the selection criteria is considered valid (as if an OR operand 
was in place); the selection values are not cumulative criteria (as if an AND 
operand was in place). 


The difference between ALL and EQL is that the values specified with ALL 
must exist, but other unspecified values can exist also. EQL requires that all 
values specified must exist, and all others may not. For example, to request those 
processes whose current privileges include TMPMBX (temporary mailbox) and 
OPER (operator), but may include other privileges, specify the ALL keyword. 

To request those processes whose current privileges are TMPMBX and OPER 
exclusively, specify the EQL keyword. 


Use the FSCONTEXT function to set up selection criteria for the F$PID function. 


The F$CONTEXT function is called as many times as necessary to produce the 
criteria needed; however, each call can specify only one selection item. Lists of 
item values are allowed, where appropriate, and more than one context can be 
operated upon at a time. 


Examples 


Lexical Functions 
FSCONTEXT 


After establishing the selection criteria with appropriate calls to FSCONTEXT, 
F$PID is called repeatedly to return all the process identification (PID) numbers 
that meet the criteria specified in the FSCONTEXT function. When there are no 
more such processes, the F$PID function returns a null string. 


After the F$PID function is called, the context symbol is considered “frozen”; 
F$CONTEXT cannot be called again with the same context symbol until the 
associated context selection criteria have been deleted. If you attempt to set up 
additional selection criteria with the same context symbol, an error message is 
displayed. However, the context and selection criteria are not affected and calls 
to the F$PID function can continue. 


The F$CONTEXT function uses process memory to store the selection criteria. 
This memory is deleted under two circumstances. Memory is deleted when the 
F$PID function is called and a null string ("") is returned—that is, when all 
processes that meet the selection criteria have been returned. Memory also is 
deleted if the CANCEL selection-item keyword is used in a call to FFCONTEXT 
with an established context. This type of call is appropriate for a Ctrl/Y operation 
or another condition handling routine. 


1. $!Establish an error and Ctrl1/Y handler 
$! 

$ ON ERROR THEN GOTO error 

$ ON CONTROL _Y THEN GOTO error 


$! 

$ ctx = ut 

$ temp = FSCONTEXT ("PROCESS", ctx, "NODENAME", "*","EQL") 

$ temp = FSCONTEXT ("PROCESS", ctx, "USERNAME", "M*,SYSTEM","EQL") 

$ temp = FSCONTEXT ("PROCESS", ctx, "CURPRIV", "SYSPRV,OPER", "ALL") 


$!Loop over all processes that meet the selection criteria. 
$!Print the PID and the name of the image for each process. 
$! 
$loop: 
$ pid = FSPID(ctx) 
$ IF pid .EQS. "" 
$ THEN 
GOTO endloop 
ELSE 
image = F$GETJPI(pid, "IMAGNAME") 
SHOW SYMBOL pid 
WRITE SYSSOUTPUT image 


Tt Ti? TH TT TH 


$!The loop over the processes has ended. 
$! 

$endloop: 

$! 


$ EXIT 

$! 

$!Error handler. Clean up the context’s memory with 
$!the CANCEL selection item keyword. 

$! 

Serror: 

$ IF FS$TYPE(ctx) .eqs. "PROCESS CONTEXT" THEN - 

_$ temp = FSCONTEXT ("PROCESS", ctx, "CANCEL") 

$! 

$ EXIT 


In this example, FSCONTEXT is called three times to set up selection criteria. 
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The first call requests that the search take place on all nodes in the cluster. 
The second call requests that only the processes whose user name either 
starts with an “M” or is “SYSTEM” be processed. The third call restricts the 
selection to those processes whose current privileges include both SYSPRV 
(system privilege) and OPER (operator) and can have other privileges set. 


The command lines between the labels “loop” and “endloop” continually 

call F$PID to obtain the processes that meet the criteria set up in the 
F$CONTEXT calls. After retrieving each PID, F$GETJPI is called to return 
the name of the image running in the process. Finally, the procedure displays 
the name of the image. 


In case of error or a Ctrl/Y operation, control is passed to error and the 
context is closed if necessary. In this example, note the check for the symbol 
type PROCESS_CONTEXT. If the symbol has this type, selection criteria 
must be canceled by a call to FSCONTEXT. If the symbol is not of the type 
PROCESS_CONTEXT, either selection criteria have not been set up yet in 
F$CONTEXT, or the symbol was used with F$PID until an error occurred or 
until the end of the process list was reached. 


f$context("process",ctx,"prcnam ","symbiont*,mcote*","eql") 
£$context("process",ctx,"prcnam ","symbiont*,mcote* ","neq") 


f$context("process",ctx,"prcnam ","mcote* ","neq") 
£$context("process",ctx,"prcnam ","symbiont*","neq") 


This example shows three sets of lexicals showing the difference between 
the EQL and the NEQ selection values. The first lexical function (with EQL) 
passes back all processes with symbiont and mcote in the process name. The 
second and third lexical functions (with NEQ) are equivalent in that they 
both will pass back all processes (processes that do not have symbiont in the 
process name, or processes that do not have mcote in the process name.) 


F$CSID 


Format 


Lexical Functions 
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Returns an identification number from a VMScluster system and updates the 
context symbol to point to the current position in the system’s cluster node list. 


F$CSID(context-symbol) 


Return Value 


Arguments 


Description 


A character string containing the system cluster identification number in the 
system’s list of clustered nodes. If the current system is not a member of a 
cluster, the first return value is null. After the last system cluster identification 
number is returned, the F$CSID function returns a null string ("""). 


context-symbol 

Specifies a symbol that DCL uses to store a pointer into the system’s list of 
clustered nodes. The F$CSID function uses this pointer to return a cluster 
identification number. 


Specify the context-symbol argument by using a symbol. The first time you use 
the F$CSID function, use a symbol that is either undefined or equated to the null 
string. 


If the context-symbol argument is undefined or equated to a null string, the 
F$CSID function returns the cluster identification number of the first system 
in the system’s cluster node list. Subsequent calls to the F$CSID function will 
return the cluster identification number of the rest of the nodes in the cluster. 


The F$CSID function returns a cluster identification number, and updates the 
context symbol to point to the current position in the system’s cluster node list. 


If the current system is not a member of a cluster, the first return value is null. 


You can use the F$CSID function to obtain all of the cluster identification 
numbers on the system. For each cluster identification returned, the FSGETSYI 
function can be used to obtain information about the particular system. 


Once the context-symbol argument is initialized by the first call, each 
subsequent F$CSID function call returns the cluster identification number of 
another node in the cluster. (Note that the cluster identification numbers are 
returned in random order.) After the cluster identification number of the last 
system in the list is returned, the F$CSID function returns a null string. 
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$ IF F$GETSYI("CLUSTER_ MEMBER" ) -EQS. "FALSE" THEN GOTO NOT CLUSTER 
$ CONTEXT = "" 

SSTART: 

id = FSCSID (CONTEXT) 

IF id .EQS. "" THEN EXIT 

nodename = FSGETSYI ("NODENAME", , id) 

WRITE SYSSOUTPUT nodename 

GOTO start 

SNOT_CLUSTER: 

$ WRITE SYSSOUTPUT "Not a member of a cluster." 
$ EXIT 


MMMM NM 


This command procedure uses the F$CSID function to display a list of cluster 
system names. The assignment statement declares the symbol CONTEXT, which 
is used as the context-symbol argument for the F$CSID function. Because 
CONTEXT is equated to a null string, the F$CSID function will return the first 
cluster identification number in the cluster node list. 


If the F$CSID function returns a null value, then the command procedure either 
is at the end of the list, or is attempting this operation on a non-clustered node. 


_ The call to FSGETSYI checks. whether the current node is a member of a cluster. 


The command procedure will exit on this condition. 


If the F$CSID function does not return a null value, then the command procedure 
uses the identification number as the third argument to the FSGETSYI function 
to obtain the name of the system. The name is then displayed using the WRITE 
command. 
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Format 
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Converts the specified bits in the specified character string to a signed number. 


F$CVS\(start-bit,number-of-bits,string) 


Return Value 


Arguments 


Examples 


The integer equivalent of the extracted bit field, converted as a signed value. 


_ Start-bit 


Specifies the offset of the first bit to be extracted. The low-order (rightmost) bit of 
a string is position number 0 for determining the offset. Specify the offset as an 
integer expression. 


If you specify an expression with a negative value, or with a value that exceeds 
the number of bits in the string, then DCL displays the INVRANGE error 
message. 


number-of-bits . 
Specifies the length of the bit string to be extracted, which must be less than or 
equal to the number of bits in the string. 


If you specify an expression with a negative value, or with a value that is invalid 
when added to the bit position offset, then DCL displays the INVRANGE error 
message. 


string 
Specifies the string from which the bits are taken. Specify the string as a 
character string expression. 


1. 32] = $X2B 


W SYMBOL A 


FSCVSI(0,4,A) 
HOW SYMBOL X 
= -5 Hex = FFFFFFFB Octal = 37777777773 


This example uses an arithmetic overlay to assign the hexadecimal value 2B 
to all 32 bits of the symbol A. For more information on arithmetic overlays, 
see the description of the assignment statement (=). 


The symbol A has a string value after the overlay because it was previously 
undefined. (If a symbol is undefined, it has a string value as a result of an 
arithmetic overlay. If a symbol was previously defined, it retains the same 
data type after the overlay.) The hexadecimal value 2B corresponds to the 
ASCII value of the plus sign (+). 


Next, the F$CVSI function extracts the low-order 4 bits from the symbol A; 
the low-order 4 bits contain the binary representation of the hexadecimal 
value B. These bits are converted, as a signed value, to an integer. The 
converted value, —5, is assigned to the symbol X. 
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2. 


$ SYM[0,32] = $X2A 
$ SHOW SYMBOL SYM 
SYM = WR oe 
$ Y = FSCVSI(0,33,SYM) 
%DCL-W-INVRANGE, field specification is out of bounds - check sign and size 
$ SHOW SYMBOL Y 
$DCL-W-UNDSYM, undefined symbol - check spelling 


In this example, the width argument specified with the F$CVSI function is 
too large. Therefore, DCL issues an error message and the symbol Y is not 
assigned a value. 


FSCVTIME 


Format 
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Converts absolute or a combination time string to a string of the form yyyy-mm- 
dd hh:mmi:ss.cc. The F$CVTIME function can also return information about 
absolute, combination, or delta time string. 


FSCVTIME([input_time] [,output_time_format] [,output_field]) 


Return Value 


Arguments 


A character string containing the requested information. 


input_time 

Specifies a string containing absolute, a delta, or a combination time, or TODAY, 
TOMORROW, or YESTERDAY. Specify the input time string as a character string 
expression. If the input_time argument is omitted or is specified as a null string 
(""), the current system date and time, in absolute format, is used. If parts of the 
date field are omitted, the missing values default to the current date. If parts of 
the time field are omitted, the missing values default to zero. 


For more information on these time formats, see the OpenVMS User’s Manual. 


If the input_time argument is a delta time, you must specify the 
output_time_format argument as DELTA. 


output_time_format 

Specifies the time format for the information you want returned. Specify 
the output_time_format argument as one of the following character string 
expressions: 


ABSOLUTE The requested information should be returned in absolute 
time format, which is dd-mmm-yyyy hh:mm:ss.cc. Single- 
digit days are returned with no leading space or zero. 


COMPARISON The requested information should be returned in the form 
(default) yyyy-mm-dd hh:mm:ss.cc (used for comparing two times). 


DELTA The requested information should be returned in delta 
format, which is dddd-hh:mm:ss.cc. If you specify DELTA 
as the output_time_format argument, then you must 
also provide a delta time specification for the input_time 
argument. 


output_field 

Specifies a character string expression containing one of the following (do not 
abbreviate): DATE, MONTH, DATETIME (default), SECOND, DAY, TIME, 
HOUR, WEEKDAY, HUNDREDTH, YEAR, MINUTE. The information is 
returned in the time format specified by the output_time_format argument. 
If the input_time argument is a delta time and the output_time_format 
argument is DELTA, you cannot specify MONTH, WEEKDAY, or YEAR. 


When the weekday is returned, the first letter is in uppercase, and the following 
letters are in lowercase. 
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When using the F$CVTIME function, you can omit optional arguments that can 
be used to the right of the last argument you specify. However, you must include 
commas (,) as placeholders if you omit optional arguments to the left of the last 
argument you specify. 


When specifying the input time argument in either absolute or combination time 
format, you can specify ABSOLUTE or COMPARISON as the output_time_ 
format argument; you cannot specify DELTA. 


When specifying the input_time argument in delta time format, you must specify 
DELTA as the output_time_format argument. 


1. 


$ TIME = FSTIME() 
$ SHOW SYMBOL TIME 
TIME = "14-DEC-1994 10:56:23.10" 
$ TIME = FSCVTIME(TIME) 
$ SHOW SYMBOL TIME 
TIME = "1994-12-14 10:56:23.10" 


This example uses the F$TIME function to return the system time as a 
character string and to assign the time to the symbol TIME. Then the 
F$CVTIME function is used to convert the system time to an alternate time 
format. Note that you do not need to place quotation marks (“”) around the 
argument TIME because it is a symbol. Symbols are automatically evaluated 
when they are used as arguments for lexical functions. 


You can use the resultant string to compare two dates (using .LTS. and .GTS. 
operators). For example, you can use F$CVTIME to convert two time strings 
and store the results in the symbols TIME_1 and TIME_2. You can compare 

the two values, and branch to a label, based on the following results: 


$ IF TIME 1 .LTS. TIME 2 THEN GOTO FIRST 


$ NEXT = FSCVTIME( "TOMORROW", , "WEEKDAY" ) 
$ SHOW SYMBOL NEXT 
NEXT = "Tuesday" 


In this example, the F$CVTIME returns the weekday that corresponds 

to the absolute time keyword “TOMORROW”. You must enclose the 
arguments “TOMORROW” and “WEEKDAY” in quotation marks because 
they are character string expressions. Also, you must include a comma as a 
placeholder for the output_time_format argument that is omitted. 


FSCVUI 


Format 
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Extracts bit fields from character string data and converts the result to an 
unsigned number. 


F$CVUI(start-bit, number-of-bits, string) 


Return Value 


Arguments 


Example 


The integer equivalent of the extracted bit field, converted as an unsigned value. 


start-bit 

Specifies the offset of the first bit to be extracted. The low-order (rightmost) bit of 
a string is position number 0 for determining the offset. Specify the offset as an 
integer expression. 


If you specify an expression with a negative value, or with a value that exceeds 
the number of bits in the string, DCL displays the INVRANGE error message. 


number-of-bits 
Specifies the length of the bit string to be extracted, which must be less than or 
equal to the number of bits in the string argument. 


If you specify an expression with a negative value, or with a value that is 
invalid when added to the bit position offset, DCL displays the INVRANGE error 
message. 


string 
Specifies the character string to be edited. 


[0,32] = %X2B 
HOW SYMBOL A 

= We 

= FSCVUI(0,4,A) 

HOW SYMBOL X 

= 11 Hex = 0000000B Octal = 00000000013 


SA 
$s 
A 
$ X 
§-§ 
X 
This example uses an arithmetic overlay to assign the hexadecimal value 2B to 
all 32 bits of the symbol A. The symbol A has a string value after the overlay 
because it was previously undefined. (If a symbol is undefined, it has a string 
value as a result of an arithmetic overlay. If a symbol was previously defined, 


it retains the same data type after the overlay.) The hexadecimal value 2B 
corresponds to the ASCII character “+”. 


Next, the F$CVUI function extracts the low-order 4 bits from the symbol A; the 
low-order 4 bits contain the binary representation of the hexadecimal value B. 
These bits are converted, as a signed value, to an integer. The converted value, 
11, is assigned to the symbol X. 
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Format 


Returns the device names of all devices on a system that meet the specified 
selection criteria. 


Note that the device names are returned in random order. 


F$DEVICE([search_devnam],[devclass],[devtype], [stream-id]) 


Return Value 


Arguments 


A character string containing the name of a device in the system’s list of devices. 
After the last device name in the system’s device list is returned, the FSDEVICE 
function returns a null string (""). 


search_devnam 

Specifies the name of the device for which FSDEVICE is to search. The asterisk 
(*) and the percent sign (% ) wildcard characters are allowed in the search_ 
devnam argument. 


Specify the search_devnam argument as a character string expression. 


devclass 

Specifies the device class for which F$DEVICE is to search. Specify the devclass 
argument as a character string expression that corresponds to a valid device class 
name. See Table DCLI-7 under F$GETDVI. 


devtype 

Specifies the device type for which F$DEVICE is to search. Specify the devtype 
argument as a character string expression that corresponds to a valid type name. 
Valid type names can be found in Table DCLI-8 under F$GETDVI. 


Note 
Specifying a device type without specifying a device class will result in an 
error. 
stream-id 


| A positive integer representing the search stream identification number. 
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The search stream identification number is used to maintain separate search 
contexts when you use the F$DEVICE function more than once and when you 
supply different search criteria. If you use the F$/DEVICE function more than 
once in a command procedure and if you also use different search criteria, specify 
stream-id arguments to identify each search separately. 


If the search criteria are changed in a call before the device name list is 
exhausted, the context will be reinitialized and the search will restart. 


If you omit the stream-id argument, the F$DEVICE function assumes an 
implicit single search stream. That is, the FSDEVICE function starts searching 
at the beginning each time you specify different search criteria. 


Description 


Example 


Lexical Functions 
| FSDEVICE 


The F$DEVICE function allows you to search for devices that meet certain search 
criteria by using the $DEVICE_SCAN system service. 


The F$DEVICE function allows asterisk (*) and percent sign (%) wildcard 
character searches based on the device name, the device class, or the device type. 


You can use the F$DEVICE function in a loop in a command procedure to 
return device names that match the specified selection criteria. Each time the 
F$DEVICE function is executed, it returns the next device on the system that 
matches the selection criteria. Note that devices are returned in no particular 
order. After the last device name is returned, the next FS{DEVICE function 
returns a null string. 


Note that you must maintain the context of the search string explicitly (by 
specifying the stream-id argument) or implicitly (by omitting the stream-id 
argument). In either case, you must specify the same selection criteria each time 
you execute the FSDEVICE system service with the same (explicit or implicit) 
stream. 


$ START: 

$ DEVICE _NAME = FSDEVICE("*0:", "DISK", "RA60") 
$ IF DEVICE NAME .EQS. "" THEN EXIT 

$ SHOW SYMBOL DEVICE_NAME 

$ GOTO START 


This command procedure displays the device names of all the RA60s on a unit 
numbered 0. 


Because no stream-id argument is specified, FSDEVICE uses an implicit search 
stream. Each subsequent use of the FSDEVICE function uses the same search 
criteria to return the next device name. After the last device name is displayed, 
the FS{DEVICE function returns a null string and the procedure exits. 


DCLI-305 


Lexical Functions 
FSDIRECTORY 


FSDIRECTORY 


Format 


Returns the current default directory name string. The FSDIRECTORY function 
has no arguments, but must be followed by parentheses. 


F$DIRECTORY() 


Return Value 


Arguments 


Description 


Example 
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A character string for the current default directory name, including brackets ([]). 
If you use the SET DEFAULT command and specify angle brackets (<>) in a 
directory specification, the FS|DIRECTORY function returns angle brackets in the 
directory string. 


None. 


You can use the F$SDIRECTORY function to save the name of the current default 
directory in a command procedure, to change the default to another directory to 
do work, and to later restore the original setting. 


$ SAVE DIR = FSDIRECTORY() 
$ SET DEFAULT [MALCOLM.TESTFILES] 


$ SET DEFAULT ‘SAVE DIR’ 


This example shows an excerpt from a command procedure that uses the 
F$DIRECTORY function to save the current default directory setting. The 
assignment statement equates the symbol SAVE_DIR to the current directory. 
Then the SET DEFAULT command establishes a new default directory. Later, 
the symbol SAVE_DIR is used in the SET DEFAULT command that restores the 
original default directory. 


Note that you can use the FSENVIRONMENT function with the DEFAULT 
keyword to return the default disk and directory. You should use the 
F$ENVIRONMENT function rather than the FSDIRECTORY function in 
situations involving more than one disk. 


FSEDIT 


Format 


Lexical Functions 
FSEDIT 


Edits the character string based on the edits specified in the edit-list argument. 


F$EDIT(string, edit-list) 


Return Value 


Arguments 


Examples 


A character string containing the specified edits. 


string 
Specifies a character string to be edited. Quoted sections of the string are not 
edited. 


edit-list 
Specifies a character string containing one or more of the following keywords 
which specify the types of edits to be made to the string: 


Edit Action 

COLLAPSE Removes all spaces or tabs. 

COMPRESS Replaces multiple spaces or tabs with a single space. 
LOWERCASE Changes all uppercase characters to lowercase. 
TRIM Removes leading and trailing spaces or tabs. 
UNCOMMENT Removes comments. 

UPCASE Changes all lowercase characters to uppercase. 


If you specify more than one keyword, separate them with commas (, ). Do not 
abbreviate these keywords. 


Edits are not applied to quoted sections of strings. Therefore, if a string contains 
quotation marks (“”), the characters within the quotation marks are not affected 
by the edits specified in the edit list. 


Note 


When UPCASE is specified with LOWERCASE in an edit-list, UPCASE 
takes precedence. 


1. $ LINE=" THIS LINE CONTAINS A'"" QUOTED '"" WORD" 
$ SHOW SYMBOL LINE 
LINE = " THIS LINE CONTAINS A" QUOTED " WORD" 


$ NEWLINE = FSEDIT(LINE, "COMPRESS, TRIM") 
$ SHOW SYMBOL NEW LINE 
NEW LINE = "THIS LINE CONTAINS A" QUOTED “ WORD" 


This example uses the F$EDIT function to compress and trim a string by 
replacing multiple blanks with a single blank, and by removing leading and 
trailing blanks. The string LINE contains quotation marks around the word 
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QUOTED. (To enter quotation marks into a character string, use double 
quotation marks in the assignment statement.) 


Note that the F$EDIT function does not compress the spaces in the quoted 
section of the string; therefore, the spaces are retained around the word 
QUOTED. 


$ LOOP: 

$ READ/END_OF_ FILE = DONE INPUT FILE RECORD 
$ RECORD = FSEDIT(RECORD, "TRIM, UPCASE") 

$ WRITE OUTPUT FILE RECORD 

$ GOTO LOOP 


This example sets up a loop to read records from a file, to edit them, and to 
write them to an output file. The edited records have leading and trailing 
blanks removed, and are converted to uppercase. 


$ UNCOMMENT LINE = FSEDIT("$ DIR ! THIS IS THE COMMENT", "UNCOMMENT" ) 
$ SHOW SYMBOL UNCOMMENT LINE 
$ UNCOMMENT LINE = "$ DIR" 


This example uses the F$EDIT function to remove comments. 


FSELEMENT 


Format 


Lexical Functions 
FSELEMENT 


Extracts one element from a string of elements. 


FSELEMENT(element-number, delimiter, string) 


Return Value 


Arguments 


Examples 


A character string containing the specified element. 


element-number 

Specifies the number of the element to extract (numbering begins with zero). 
Specify the element-number argument as an integer expression. If the 
element-number argument exceeds the number of elements in the string, 
F$ELEMENT returns the delimiter. 


delimiter 
Specifies a character used to separate the elements in the string. Specify the 
delimiter as a character string expression. 


string 
Specifies a string containing a deh list of elements. Specify the string asa 
character string expression. 


1. $ DAY LIST = "MON/TUE/WED/THU/FRI/SAT/SUN" 
$ INQUIRE DAY “ENTER DAY (MON TUE WED THU FRI SAT SUN)" 


$ NUM = 0 

$ LOOP 

$ LABEL = FSELEMENT(NUM,"/",DAY_ LIST) 
$ IF LABEL .EQS. "/" THEN GOTO END 

$ IF DAY .EQS. LABEL THEN GOTO ‘LABEL’ 
$ NUM = NUM +1 

$ GOTO LOOP 

$ 

$ 


This example sets up a loop to test an input value against the elements in a 
list of values. If the value for DAY matches one of the elements in DAY_LIST, 
control is passed to the corresponding label. If the value returned by the 
F$ELEMENT function matches the delimiter, the value DAY was not present 
in the DAY_LIST, and control is passed to the label END. 
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2. 


NUM = FSELEMENT(NEXT,",", CHAPTERS) 
IF (NUM .NES. ",") 
THEN 
RUN INDEX CHAP’ NUM’ 
GOTO LOOP 
$ ENDIF 


This example processes files named CHAP1, CHAP2, ... CHAP6, CHAPA, 
CHAPB, and CHAPC, in that order. (Zero is included in the CHAPTERS 
string to initialize the procedure logic.) NEXT is initialized to zero. The 
procedure enters the loop. In the first iteration, NEXT is incremented to 1 
and the result of the FSELEMENT call is the string “1”. The procedure runs 
the index, chapter 1. In the second iteration, NEXT is incremented to 2 and 
the result of the FSELEMENT call is the string “1”. The procedure runs the 
index, chapter 2. Processing continues until the result of the FEELEMENT 
call is the delimiter specified in the call. 


$ 
$ 
$ 
$ 
$ 
$ NEXT = NEXT + 1 
$ 
$ 
$ 
$ 
$ 
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FSENVIRONMENT 
Returns information about the current DCL command environment. 


Format 
FSENVIRONMENT(item) 


Return Value 


Information that corresponds to the specified item. The return value can be 
either an integer or a character string, depending on the specified item. 


Argument 
item 


Specifies the type of information to be returned. Specify one of the following 
keywords (do not abbreviate these keywords): 


Item Data Type Information Returned 
CAPTIVE String TRUE if you are logged in to a captive 


account. The system manager can define 
captive accounts in the user authorization 
file (UAF) by using the Authorize utility 
(AUTHORIZE). 


CONTROL. String Control characters currently enabled with 
SET CONTROL. Multiple characters 
are separated by commas; if no control 
characters are enabled, the null string ("") 
is returned. 


DEFAULT String Current default device and directory name. 
The returned string is the same as SHOW 
DEFAULT output. 


DEPTH Integer Current command procedure depth. The 
command procedure depth is 0 when you 
log in interactively and when you submit a 
batch job. The command procedure depth is 
1 when you execute a command procedure 
interactively or from within a batch job. A 
nested command procedure has a depth of 
1 greater than the depth of the command 
procedure from which the nested procedure 
is executed. 

DISIMAGE String TRUE if you are logged in to an account 
that does not allow the use of the RUN and 
MCR commands or foreign commands. The 
system manager can add or remove the 
DISIMAGE attribute for accounts in the 
UAF by using AUTHORIZE. 


INTERACTIVE | String TRUE if the process is executing 
interactively. 
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Item Data Type Information Returned 
KEY_STATE String Current locked keypad state. See the 
description of the DEFINE/KEY command 
for more information on keypad states. 
MAX_DEPTH Integer Maximum allowable command procedure 
depth. 


MESSAGE String Current setting of SET MESSAGE 
qualifiers. Each qualifier in the 
string is prefaced by a slash 
(/); therefore, the output from 
FSENVIRONMENT(“MESSAGE”) can be 
appended to the SET MESSAGE command 
to form a valid DCL command line. 


NOCONTROL String Control characters currently disabled with 
SET NOCONTROL. Multiple characters 
are separated by commas (, ); if no control 
characters are disabled, the null string is 
returned. 


ON_CONTROL_Y String If issued from a command procedure, 
returns TRUE if ON_CONTROL_Y is set. 
ON_CONTROL_Y always returns FALSE 
at DCL command level. 


ON_SEVERITY String If issued from a command procedure, 
returns the severity level at which the 
action specified with the ON command is 
performed. ON_SEVERITY returns NONE 
when SET NOON is in effect or at DCL 
command level. 

OUTPUT_RATE String Delta time string containing the default 
output rate, which indicates how often data 
is written to the batch job log file while the 
batch job is executing. OUTPUT_RATE 

returns a null string if used interactively. 

PROCEDURE String File specification of the current command 
procedure. If used interactively, the 
terminal device name is returned. 


PROMPT String Current DCL prompt. 

PROMPT_CONTROL _ String TRUE if a carriage return and line feed 
precede the prompt. 

PROTECTION String Current default file protection. The string 


can be used with the SET PROTECTION 
/DEFAULT command to form a valid DCL 
command line. 

RESTRICTED String TRUE if you are logged in to a restricted 
account. The system manager can define 


restricted accounts in the UAF by using 
AUTHORIZE. 
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Item Data Type Information Returned 

SYMBOL_SCOPE String [NOJLOCAL, [NO]GLOBAL to indicate the 
current symbol scoping state. 

VERB_SCOPE String [NOJLOCAL, [NO]GLOBAL to indicate the 
current symbol scoping state for verbs. (For 
more information, see the description of the 
SET SYMBOL command.) 

VERIFY_IMAGE String TRUE if image verification (SET 
VERIFY=IMAGE) is in effect. If image 
verification is in effect, then the command 
procedure echoes input data read by 
images. 

VERIFY_PREFIX String Returns the prefix control string set by 

. means of the SET PREFIX command. 
VERIFY_ String TRUE if procedure verification 
PROCEDURE SET VERIFY=PROCEDURE is in effect. If 


1. 


command verification is in effect, then the 
command procedure echoes DCL command 
lines. 


$ SAVE MESSAGE = FSENVIRONMENT( "MESSAGE" ) 
$§ SET MESSAGE/NOFACILITY/NOIDENTIFICATION 


$ SET MESSAGE’SAVE MESSAGE‘ 


This example uses the FSENVIRONMENT function to save the current 
message setting before changing the setting. At the end of the command » 
procedure, the original message setting is restored. The single quotation 
marks (‘’) surrounding the symbol SAVE_MESSAGE indicate that the value 
for the symbol should be substituted. 


$ MAX = FSENVIRONMENT("MAX DEPTH") 
$ SHOW SYMBOL MAX 
MAX = 32 Hex = 00000020 Octal = 00000000040 


This example uses the FSENVIRONMENT function to determine the 


- maximum depth allowable within command procedures. 


$ SAVE PROT = FSENVIRONMENT( "PROTECTION" ) 
$ SET PROTECTION = (SYSTEM:RWED, OWNER:RWED, GROUP, WORLD) /DEFAULT 


$ SET PROTECTION = ('SAVE_PROT’)/DEFAULT 


This example uses the FSENVIRONMENT function to save the current 
default protection before changing the protection. At the end of the command 
procedure, the original protection is restored. You must place single quotation 
marks around the symbol SAVE_PROT to request symbol substitution. 
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FSEXTRACT 


Format 


Extracts the specified characters from the specified string. 


FSEXTRACT(start,length,string) 


Return Value 


Arguments 


Examples 
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A character string containing the characters delimited by the start and length 
arguments. 


start 

Specifies the offset of the starting character of the string you want to extract. 
Specify the start argument as an integer expression that is greater than or equal 
to zero. 


The offset is the relative position of a character or a substring with respect to 
the beginning of the string. Offset positions begin with zero. The string always 
begins with the leftmost character. . 


If you specify an offset that is greater than or equal to the length of the string, 
F$EXTRACT returns a null string (""). 


length 

Specifies the number of characters you want to extract; must be less than or 
equal to the size of the string. Specify the length as an integer expression that is 
greater than or equal to zero. 


If you specify a length that exceeds the number of characters from the offset to 
the end of the string, the FSEXTRACT function returns the characters from the 
offset through the end of the string. 


string 
Specifies the character string to be edited. Specify the string as a character string | 
expression. | 


1. $ NAME = "JOE SMITH" 
$ FIRST = FSEXTRACT(0,3,NAME) 
$ SHOW SYMBOL FIRST 
FIRST = "JOE" 


This portion of a command procedure uses the FSEXTRACT function to 
extract the first 3 characters from the character string assigned to the 
symbol NAME. The offset and length arguments are integers, and the string 
argument is a symbol. You do not need to use quotation marks (“”) around 
integers or symbols when they are used as arguments for lexical functions. 


2. 


Lexical Functions 
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$ Pl = "MYFILE.DAT" 
$ FILENAME = FSEXTRACT(0,FSLOCATE(".",P1),P1) 


This portion of a command procedure shows how to locate a character within 
a string, and how to extract a substring ending at that location. | 


The lexical function FSLOCATE gives the numeric value representing the 
offset position of a period in the character string value of Pl. (The offset 
position of the period is equal to the length of the substring before the 
period.) 


This FSLOCATE function is used as an argument in the FSEXTRACT 
function to specify the number of characters to extract from the string. If 
a procedure is invoked with the parameter MYFILE.DAT, these statements 
result in the symbol FILENAME being given the value MYFILE. 


Note that the FSLOCATE function in the above example assumes that the 
file specification does not contain a node name or a directory specification 
containing a subdirectory name. To obtain the file name from a full file 
specification, use the FSPARSE function. 


$ IF FSEXTRACT(12,2,FSTIME() ) -GES. "12" THEN GOTO AFTERNOON 
$ MORNING: 

$ WRITE SYSSOUTPUT "Good morning!" 

$ EXIT 

$ AFTERNOON: 

$ WRITE SYSSOUTPUT "Good afternoon!" 

$ EXIT 


This example shows a procedure that displays a different message, depending 
on whether the current time is morning or afternoon. It first obtains the 
current time of day by using the F$TIME function. The F$TIME function 
returns a character string, which is the string argument for the FSEXTRACT 
function. The F$TIME function is automatically evaluated when it is used as 
an argument, so you do not need to use quotation marks. 


Next, the FSEXTRACT function extracts the hours from the date and time 
string returned by F$TIME. The string returned by F$TIME always contains 
the hours field beginning at an offset of 12 characters from the start of the 
string. 

The F$EXTRACT function extracts 2 characters from the string, beginning 
at this offset, and compares the string value extracted with the string value 


12. If the comparison is true, then the procedure writes “Good afternoon!”. 
Otherwise, it writes “Good morning!”. 


Note that you can also use the F$CVTIME function to extract the hour field 
from a time specification. This method is easier than the one shown in the 
above example. 
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FSFAO 


Format 


Converts character and numeric input to ASCII character strings. (FAO stands 
for formatted ASCII output.) By specifying formatting instructions, you can 
use the F$FAO function to convert integer values to character strings, to insert 
carriage returns and form feeds, to insert text, and so on. 


F$FAO(control-string[,argumentt,...]]) 


Return Value 


Arguments 


Description 
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A character string containing formatted ASCII output. This output string is 
created from the fixed text and FAO directives in the control string. 


control-string 

Specifies the fixed text of the output string, consisting of text and any number of 
FAO directives. The control string may be any length. Specify the control string 
as a character string expression. _ 


The F$FAO function uses FAO directives to modify or insert ASCII data into the 
fixed text in the control string. . 


Table DCLI-4 lists the FAO directives you can specify in a control string. 


argument{,...] 

Specifies from 1 to 15 arguments required by the FAO directives used in the 
control string. Specify the arguments as integer or character string expressions. 
Table DCLI"-4 lists the argument types required by each FAO directive. 


FAO directives may require one or more arguments. The order of the arguments 
must correspond exactly with the order of the directives in the control string. In 
most cases, an error message is not displayed if you misplace an argument. 


If you specify an argument whose type (integer or string) does not match that of 
the corresponding directive, unpredictable results are returned. You can use the 
FSINTEGER and F$STRING lexical functions to convert arguments to the proper 
type. 


If there are not enough arguments listed, F$FAO continues reading past the end 
of an argument list. Therefore, always be sure to include enough arguments to 
satisfy the requirements of all the directives in a control string. 


If you specify an invalid parameter for any directive, you may see unexpected 
errors, which indicate that the command did not succeed. (These errors are 
passed through to you from the $FAO system service.) 


The F$FAO lexical function invokes the $FAO system service to convert character 
and numeric input to ASCII character strings. (FAO stands for formatted ASCII 
output.) By specifying formatting instructions, you can use the F$FAO function 
to convert integer values to character strings, to insert carriage returns and form 
feeds, to insert text, and so on. 
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Specify an FAO directive using any one of the following formats: 
Format Function 
!DD One directive 
In(DD) A directive repeated a specified number of times 
NlengthDD A directive that places its output in a field of a specified 

length 
In(lengthDD) A directive that is repeated a specified number of times 


and generates output fields of a specified length 


The exclamation point (!) indicates that the following character or characters 
are to be interpreted as an FAO directive. DD represents a 1- or 2-character 
uppercase code indicating the action that F$FAO is to perform. When specifying 
repeat counts, n is a decimal value specifying the number of times the directive 
is to be repeated. The length value is a decimal number that instructs F$FAO to 
generate an output field of “length” characters. 


Repeat counts and output lengths may also be specified by using a number sign 
(#) in place of absolute numeric value. If you use a number sign, you must 
specify the numeric value as an integer expression in the corresponding place in 
the argument list. 


When a variable output field is specified with a repeat count, only one length 
parameter is required, because each output string has the specified length. 


The FAO directives are grouped in the following categories: 
e Character string insertion 

¢ Zero-filled numeric conversion 

e Blank-filled numeric conversion 

e Special formatting 

e Parameter interpretation 


Table DCLI-+4 summarizes the FAO directives and shows the required argument 
types. In addition, the following sections describe output strings from directives 
that perform character string insertion, zero-filled numeric conversion, and 
blank-filled numeric conversion. 


Note 


Two types of directives that are supported by the $FAO system service are 
not supported by the DCL F$FAO lexical function. These types are: 


¢ Quadword numeric directives, which are not supported in DCL 
because all DCL numeric values are stored and manipulated as 
longwords. 


e String directives other than the !AS directive, which are not supported 
in DCL because all DCL strings are stored and manipulated by 
_ descriptor. 


For further information on the $FAO system service directive, see the 
OpenVMS System Services Reference Manual. 
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Table DCLI-4 Summary of FAO Directives 
Directive Argument Type 


Character string insertion: 


IAS String 

Zero-filled numeric conversion: 
!OB Integer 

!{OW Integer 

!OL Integer 

IXB Integer 

[XW Integer 

{XL Integer 

IZB Integer 

{ZW Integer 

ZL Integer 
Blank-filled numeric conversion: 
!'UB Integer 

{UW Integer 

UL Integer 

ISB Integer 

SW Integer 

ISL Integer 


Special formatting: 


t/ None 
i None 
y None 
! None 
1%I Integer 


Description 


Inserts a character string as is. 


Converts a byte to octal notation. 
Converts a word to octal notation. 
Converts a longword to octal notation. 
Converts a byte to hexadecimal notation. 


Converts a word to hexadecimal 
notation. 


Converts a longword to hexadecimal 
notation. 


Converts a byte to decimal notation. 
Converts a word to decimal notation. 
Converts a longword to decimal notation. 


Converts a byte to decimal notation 
without adjusting for negative numbers. 


Converts a word to decimal notation 
without adjusting for negative numbers. 


Converts a longword to decimal notation 
without adjusting for negative numbers. 


Converts a byte to decimal notation 
with negative numbers converted 
properly. 

Converts a word to decimal notation 
with negative numbers converted 
properly. 

Converts a longword to decimal notation 
with negative numbers converted 
properly. 


Inserts a carriage return and a line feed. 
Inserts a tab. 

Inserts a form feed. 

Inserts an exclamation point (!). 


Converts a longword integer to a named 
UIC in the format 
{group-identifier,member-identifier]. 


(continued on next page) 
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Table DCLI-4 (Cont.) Summary of FAO Directives 
Directive Argument Type Description 
1%S None Inserts an “s” if the most recently 


converted number is not 1. (Not 
recommended for use with multilingual 
products.) 


1[%U Integer Converts a longword integer to a 
numeric. 
UIC in the format [g,m], where g is the 
group. 
number and m is the member number. 
The directive inserts the brackets and 
the comma. 


In<...!> None Left-justifies and blank-fills all data 
represented by the instructions ... in 
fields n characters wide. 


In*c None Repeats the character represented 
by c for n times. 


In%C String Inserts a character string when the most 
recently evaluated argument has the 
value n. (Recommended for use with 
multilingual products.) 


1%E String Inserts a character string when the 
value of the most recently evaluated 
argument does not match any preceding 
!n%C directives. (Recommended for use 
with multilingual products.) 


1%F None Marks the end of a plurals statement. 
!%T Integer equal to 0 Inserts the current time. 

!%D Integer equal to 0 Inserts the current date/time. 
Argument interpretation: 

I. None Reuses the last argument. 

14 None Skips the next argument. 


Output Strings from Character String Insertion 

The !AS directive inserts a character string (specified as an argument for the 
directive) into the control string. The field length of the character string when it 
is inserted into the control string defaults to the length of the character string. 
If the default length is shorter than an explicitly stated field length, the string 
is left-justified and blank-filled. If the default length is longer than an explicitly 
stated field length, the string is truncated on the right. 


Output Strings from Zero-Filled Numeric Conversion 


Directives for zero-filled numeric conversion convert an integer (specified as an 
argument for the directive) to decimal, octal, or hexadecimal notation. The ASCII 
representation of the integer is inserted into the control string. Default output 
field lengths for the converted argument are determined as follows. 
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Directives that convert arguments to octal notation return 3 digits for byte 
conversion, 6 digits for word conversion, and 11 digits for longword conversion. 
Numbers are right-justified and zero-filled on the left. Explicit-length fields 
longer than the default are blank-filled on the left. Explicit-length fields shorter 
than the default are truncated on the left. 


Directives that convert arguments to hexadecimal notation return 2 digits for byte 
conversion, 4 digits for word conversion, and 8 digits for longword conversion. 
Numbers are right-justified and zero-filled on the left. Explicit-length fields 
longer than the default are blank-filled on the left. Explicit-length fields shorter 
than the default are truncated on the left. 


Directives that convert arguments to decimal notation return the required 
number of characters for the decimal number. Explicit-length fields longer than 
the default are zero-filled on the left. If an explicit-length field is shorter than 
the number of characters required for the decimal number, the output field is 
completely filled with asterisks (* ). 


For byte conversion, only the low-order 8 bits of the binary representation of the 
argument are used. For word conversion, only the low-order 16 bits of the binary 
representation of the argument are used. For longword conversion, the entire 
32-bit binary representation of the argument is used. 


Output Strings from Blank-Filled Numeric Conversion 


Directives for blank-filled numeric conversion convert an integer (specified as an 
argument for the directive) to decimal notation. These directives can convert the 
integer as a signed or unsigned number. The ASCII representation of the integer 
is inserted into the control string. 


Output field lengths for the converted argument default to the required number 
of characters. Values shorter than explicit-length fields are right-justified and 
blank-filled; values longer than explicit-length fields cause the field to be filled 
with asterisks. 


For byte conversion, only the low-order 8 bits of the binary representation of the 
argument are used. For word conversion, only the low-order 16 bits of the binary 
representation of the argument are used. For longword conversion, the entire 
32-bit binary representation of the argument is used. 


Output Strings from Special Formatting Directives 

The !n%C and !%E directives insert an ASCII string (based on the value of the 
most recently evaluated argument) into the output string. These directives are 
useful for inserting irregular plural nouns and verbs. 


If the most recently evaluated argument equals n, the text between one directive 
and the next is inserted into the output string. If the most recently evaluated 
argument does not equal n, the next !n%C directive is processed. 


If nm must be a negative number, you must specify it as an argument and use the 
number sign (#). 


You can specify the !n%C and !%E directives with repeat counts. If you specify 
repeat counts, the text between one directive and the next is copied to the output 
string the specified number of times. . 


The %F directive marks the end of a plurals statement. 


Examples 


Lexical Functions 
FSFAO 


$ COUNT = 57 
$ REPORT = F$FAO("NUMBER OF FORMS = !SL",COUNT) 
$ SHOW SYMBOL REPORT 

REPORT = "NUMBER OF FORMS = 57" 


In this command procedure, the FAO directive !SL is used in a control string 
to convert the number equated to the symbol COUNT to a character string. 
The converted string is inserted into the control string. 


Note that COUNT is assigned an integer value of 57. The F$FAO function 
returns the ASCII string, “NUMBER OF FORMS = 57”, and assigns the 
string to the symbol REPORT. 


$ A = "ERR" 

$ B= "IS" 

$C = "HUM" 

$ D = "AN" 

$ PHRASE = FSFAO("TO !3(AS)",A,B,C+D) 


$ SHOW SYMBOL PHRASE 
$ PHRASE = "TO ERRISHUMAN" 


In this command procedure, the !AS directive is used to insert the values 
assigned to the symbols A, B, C, and D into the control string. 


Because the specified repeat count for the !AS directive is 3, F$FAO looks 
for three arguments. The arguments in this example include the symbol A 
(“ERR”), the symbol B (“IS”), and the expression C+D (“HUMAN”). Note that 
the values of these string arguments are concatenated to form the string 
“ERRISHUMAN”. 


$ A = "ERR" 

$ B= "IS" 

$ C = "HUMAN" 

$ PHRASE = FSFAO("TO !#(#AS)",3,6,A,B,C) 


$ SHOW SYMBOL PHRASE 
$ PHRASE = "TO ERR’ IS HUMAN " 


In this command procedure, the F$FAO function is used with the !AS directive 
to format a character string. The first number sign (#) represents the repeat 
count given by the first argument, 3. The second number sign represents the 
field size given by the second argument, 6. The next three arguments (A,B,C) 
provide the strings that are placed into the control string each time the !AS 
directive is repeated. . 


Each argument string is output to a field having a length of 6 characters. 
Because each string is less than 6 characters, each field is left-justified and 
padded with blank spaces. The resulting string is assigned to the symbol 
PHRASE. 


$ OFFSPRING = 1 

$ REPORT = FSFAO- 

("There !QUL!1%Cis!%Eare!%F !-!UL !-!0UL!1%$Cchild!%Echildren!%F here",1) 
$ SHOW SYMBOL REPORT 

$ REPORT ="There is 1 child here" 


In this command procedure, the !OUL directive evaluates the argument 
OFFSPRING but does not insert the value in the output string. The !n%C 
directive inserts the character string “is” into the output string because its 
value and the value of the argument OFFSPRING match. The directives 
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!-!UL evaluate the argument a second time so that the correct character 
string can be inserted in the proper place in the output string. The !%F 

- directive marks the end of each plurals statement. The F$FAO function 
returns the ASCII string “There is 1 child here” and assigns the string to the 


symbol REPORT. 
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F$FILE_ATTRIBUTES 


Format 


Returns attribute information for a specified file. 


F$FILE_ATTRIBUTES(filespec, item) 


Return Value 


Arguments 


Description 


Either an integer or a character string, depending on the item you request. 
Table DCLI-5 shows the data types of the values returned for each item. 


filespec 
Specifies the name of the file about which you are requesting information. You 
must specify the file name as a character string expression. 


You can specify only one file name. Wildcard characters are not allowed. 


item 

Indicates which attribute of the file is to be returned. The item argument must 
be specified as a character string expression, and can be any one of the OpenVMS 
RMS field names listed in Table DCLI-—5. 


Use the F$FILE_ATTRIBUTES lexical function in DCL assignment statements 
and expressions to return file attribute information. Table DCLI-—5 lists the 
items you can specify with the F$FILE_ATTRIBUTES function, the information 
returned, and the data type of this information. 


Table DCLI-5 FS$FILE_ATTRIBUTES Items 


item Return Type Information Returned 

Al String TRUE if after-image (AJ) journaling is 
enabled; FALSE if disabled 

ALQ | Integer Allocation quantity 

BDT String Backup date/time 

BI String TRUE if before-image (BI) journaling is 
enabled; FALSE if disabled 

BKS Integer Bucket size 

BLS Integer Block size 

CBT String TRUE if contiguous-best-try; otherwise 
FALSE 

CDT String Creation date/time 

CTG String TRUE if contiguous; otherwise FALSE 

DEQ Integer Default extension quantity 

DID String Directory ID string 


(continued on next page) 
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Table DCLI-5 (Cont.) FSFILE_ATTRIBUTES Items 


Item 


DVI 
EDT 
EOF 
ERASE 


FFB 

FID 

FSZ 

GBC 

GRP 
JOURNAL_FILE 


KNOWN 


LOCKED ~ 


LRL 
MBM 
MOVE 


MRN 
MRS 
NOA 
NOBACKUP 


NOK 
ORG 
PRO 
PVN 
RAT 
RCK 
RDT 
RFM 


RU 


Return Type 


String 
String 
Integer 
String 


Integer 
String 
Integer 
Integer 
Integer 
String 


String 


String 


Integer 
Integer 
String 


Integer 
Integer 
Integer 
String 


Integer 
String 
String 
Integer 
String 
String 
String 
String 


String 


Information Returned 


Device name string 
Expiration date/time 
Number of blocks used 


TRUE if a file’s contents are erased before a 
file is deleted; otherwise FALSE 


First free byte 

File ID string 

Fixed control area size 
Global buffer count 
Owner group number 


TRUE if the file is a journal; otherwise 
FALSE 


Known file; returns TRUE or FALSE to 
indicate whether file is installed with the 
Install utility INSTALL). However, returns 
NOSUCHFILE if a file does not exist (for 
example, the file has been installed but 
subsequently deleted). 


TRUE if a file is deaccessed-locked; otherwise 
FALSE 


Longest record length 
Owner member number 


TRUE if movefile operations are enabled; 
otherwise FALSE 


Maximum record number 
Maximum record size 
Number of areas 


FALSE if the file is marked for backup; 
TRUE if the file is marked NOBACKUP 


Number of keys 

File organization; returns SEQ, REL, IDX 
File protection string 

Prolog version number 

Record attributes; returns CR, PRN, FTN, "" 
TRUE if read check; otherwise FALSE 
Revision date/time 


Record format string; returns the values 
VAR, FIX, VFC, UDF, STM, STMLF, STMCR 


TRUE if recovery unit (RU) journaling is 
enabled; returns TRUE or FALSE 


(continued on next page) 
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Table DCLI-5 (Cont.) FS$FILE_ATTRIBUTES Items 


Item Return Type Information Returned 

RVN Integer Revision number 

SHELVABLE String TRUE if the file is shelvable; otherwise 
FALSE 

SHELVED String TRUE if the file is shelved; otherwise FALSE 

STORED_ String ASCII string that represents stored 

SEMANTICS semantics 

UIC String Owner user identification code (UIC) string 

WCK String TRUE if write check; otherwise FALSE 

File attributes are stored in the file header, which is created from information in 


OpenVMS RMS control blocks. For more information on OpenVMS RMS control 
blocks, see the OpenVMS Record Management Services Reference Manual. 


1. 


$ FILE_ORG = F$FILE ATTRIBUTES ("QUEST.DAT" , "ORG" ) 
$ SHOW SYMBOL FILE ORG 
FILE _ORG = "SEQ" 


This example uses the F$FILE_ATTRIBUTES function to assign the value 
of the file organization type to the symbol FILE_ORG. The F$FILE_ 
ATTRIBUTES function returns the character string SEQ to show that 
QUEST.DAT is a sequential file. 


The QUEST.DAT and ORG arguments for the F$FILE_ATTRIBUTES function 
are string literals and must be enclosed in quotation marks (“” ) when used 
in expressions. 


$ RFM = FSFILE_ ATTRIBUTES ( "KANSAS: :USE$:[CARS]SALES.CMD", "RFM") 
$ SHOW SYMBOL RFM 

RFM = "VAR" 
This example uses the F$FILE_ATTRIBUTES function to return information 
about a file on a remote node. The function returns the record format string 
VAR, indicating that records are variable length. 
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FSGETDV! 


FS$GETDVI 


Format 


Returns a specified item of information for a specified device. 


FSGETDVI(device-name,item) 


Return Value 


Arguments 


Description 
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Hither an integer or a character string, depending on the item you request. 
Table DCLI-6 shows the data types of the values returned for each item. 


device-name 
Specifies a physical device name or a logical name equated to a physical device 
name. Specify the device name as a character string expression. 


After the device-name argument is evaluated, the FSGETDVI function examines 
the first character of the name. If the first character is an underscore (_), the 
name is considered a physical device name. Otherwise, a single level of logical 
name translation is performed and the equivalence name, if any, is used. 


item 

Specifies the type of device information to be returned. The item argument must 
be specified as a character string expression and can be any one of the items 
listed in Table DCLI-6. 


The F$GETDVI lexical function invokes the $GETDVI system service to return 
a specified item of information for a specified device. You can obtain a list of 
devices on your current system by using the lexical function FSDEVICE. Unless 
otherwise stated in the description of the item argument, F$GETDVI returns 
device information about the local node only. 


This lexical function allows a process to obtain information for a device to which 
the process has not necessarily assigned a channel. 


The F$GETDVI function returns information on all items that can be specified 
with the $GETDVI system service. In addition to the items that the $GETDVI1 
system service allows, the FS{GETDVI function allows you to specify the item 
EXISTS. 


Table DCLI-6 lists the items you can specify with the F$SGETDVI function, 

the type of information returned, and the data types of the return values. In 
addition to the return information listed in Table DCLI-6, the F$GETDVI lexical 
function returns any error messages generated by the system service $GETDVI. 
Table DCLI-7 lists the values returned by the DEVCLASS item. Table DCLI-8 
lists the values returned by the DEVTYPE item. For more information on the 
$GETDVI system service and the items you can specify, see the OpenVMS System 
Services Reference Manual. 


Table DCLI-6 FS$GETDVI Items 


Item 


ACPPID 
ACPTYPE 


ALL 


ALLDEVNAM 
ALLOCLASS 


ALT_HOST_AVAIL 


ALT_HOST_NAME 
ALT_HOST_TYPE 


AVL 
CCL 


CLUSTER 
CONCEALED 


CYLINDERS 
DEVBUFSIZ 
DEVCHAR 
DEVCHAR2 
DEVCLASS 


DEVDEPEND 
DEVDEPEND2 
DEVLOCKNAM 
DEVNAM 
DEVSTS 
DEVTYPE 


DEVICE_TYPE_NAME 


Return 
Type 

String 
String 


String 


String 
Longword 
integer 
between 0 
and 255 


String 


String 
String 


String 
String 


Integer 
String 


Integer 
Integer 
Integer 
Integer 
Integer 


Integer 
Integer 
String 
String 
Integer 
Integer 


String 


Lexical Functions 
FSGETDVI 


Information Returned’ 


Ancillary control process (ACP) identification. 


ACP type code, as one of the following strings: 
F11V1, F11V2, JNL, MTA, NET, REM, or ILLEGAL 
if the device is not mounted or is mounted using 
the /FOREIGN qualifier. 


TRUE or FALSE to indicate whether the device is 
allocated. 


Allocation class device name. 
Allocation class of the host. 


TRUE or FALSE to indicate whether the host 
serving the alternate path is available. ’ 


Name of the host serving the alternate path. 


Hardware type of the host serving the alternate 
path. | 


TRUE or FALSE to indicate whether the device is 
available for use. 


TRUE or FALSE to indicate whether the device is a 
carriage control device. 


Volume cluster size. 


TRUE or FALSE to indicate whether the logical | 
device name translates to a concealed device. 


Number of cylinders on the volume (disks only). 
Device buffer size. 

Device characteristics. 

Additional device characteristics. 


Device class. (See Table DCLI-7 for a list of the 
values returned.) 


Device-dependent information. 
Additional device-dependent information. 
A unique lock name for the device. 
Device name. 

Device-dependent status information. 


Device type. (See Table DCLI-8 for a list of the 
values returned.) 


Device type name. 


1fn addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 


the system service $GETDVI. 


(continued on next page) 
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Table DCLI-6 (Cont.) FSGETDVI Items 


Return 
Item Type 
DFS_ACCESS String 
DIR String 
DMT String 

DUA String 
ELG String 
ERRCNT Integer 
EXISTS String 
FOD String 
FOR ; String 
FREEBLOCKS Integer 
FULLDEVNAM String 
GEN String 
HOST_AVAIL String 
HOST_COUNT Integer 
HOST_NAME String 
HOST_TYPE String 
IDV String 
LOCKID Integer 
LOGVOLNAM String 
MAXBLOCK Integer 
MAXFILES Integer 
MBX String 
MEDIA_ID String 


Information Returned’ 


TRUE or FALSE to indicate whether the device is a 
virtual disk connected to a remote Distributed File 
System (DFS) server. 


TRUE or FALSE to indicate whether the evi is 
directory structured. 


TRUE or FALSE to indicate whether the device is 
marked for dismount. 


TRUE or FALSE to indicate whether the device is a 
generic device. 


TRUE or FALSE to indicate whether the device has 
error logging enabled. 


Error count. 


TRUE or FALSE to indicate whether the device 
exists on the system. 


TRUE or FALSE to indicate whether the device is a 
files-oriented device. 


TRUE or FALSE to indicate whether the device is 
mounted using the /FOREIGN qualifier. 


Number of free blocks on the volume (disks only). 
Fully qualified device name. 


TRUE or FALSE to indicate whether the device is a 
generic device. 


TRUE or FALSE to indicate whether the host 
serving the primary path is available. 


Number of hosts that make the device available to 
other nodes in the VMScluster. 


Name of the host serving the primary path. 


Hardware type of the host serving the primary 
path. 


TRUE or FALSE to indicate whether the aan is 
capable of providing input. 


Clusterwide lock identification. 
Logical volume name. 
Number of logical blocks on the volume. 


Maximum number of files on the volume (disks 
only). 


TRUE or FALSE to indicate whether the device is a 
mailbox. 


Nondecoded media ID. 


1In addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 


the system service $GETDVI. 
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Table DCLI-6 (Cont.) FSGETDVI Items 


Item 


MEDIA_NAME 
MEDIA_TYPE 
MNT 


MOUNTCNT 
NET 


NEXTDEVNAM 
ODV 


OPCNT 
_ OPR 


OWNUIC 
PID 
RCK 


RCT 
REC 


RECSIZ 
REFCNT 
REMOTE_DEVICE 


RND 
ROOTDEVNAM 
RTM 

SDI 


SECTORS 
SERIALNUM 
SERVED_DEVICE 


Return 
Type 


String 
String 
String 


Integer 
String 


String 
String 


Integer 
String 


String 
String 
String 
String 


String 


Integer 
Integer 
String 


String 
String 
String 
String 


Integer 
Integer 
String 


Lexical Functions 
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Information Returned’ 


Either the name of the disk or the tape type. 
Device name prefix. 


TRUE or FALSE to indicate whether the device is 
mounted. 


Mount count. 


TRUE or FALSE to indicate whether the device is a 
network device. 


Device name of the next volume in a volume set 
(disks only). 


TRUE or FALSE to indicate whether the device is 
capable of providing output. 


Operation count. 


TRUE or FALSE to indicate whether the device is 
an operator. 


User identification code (UIC) of the device owner. 
Process identification number of the device owner. 


TRUE or FALSE to indicate whether the device has 
read checking enabled. 


TRUE or FALSE to indicate whether the disk 
contains RCT. 


TRUE or FALSE to indicate whether the device is 
record oriented. 


Blocked record size. 
Reference count of processes using the device. 


TRUE or FALSE to indicate whether the device is a 
remote device. 


TRUE or FALSE to indicate whether the device 
allows random access. 


Device name of the root volume in a volume set 
(disks only). 


TRUE or FALSE to indicate whether the device is a 
real-time device. 


TRUE or FALSE to indicate whether the device is 
single-directory structured. 


Number of sectors per track (disks only). 
Volume serial number (disks only). 


TRUE or FALSE to indicate whether the device is a 
served device. 


1In addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 


the system service $GETDVI. 
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Table DCLI-6 (Cont.) FSGETDVI Items 


Item 


SET_HOST_TERMINAL 


SHDW_CATCHUP_ 
COPYING 
SHDW_MASTER 


SHDW_MASTER_NAME 


SHDW_MEMBER 
SHDW_MERGE_COPYING 


SHDW_NEXT_MBR_NAME 


SHR 
SPL 


SPLDEVNAM 
SQD 


STS 
SWL 


TRACKS 
TRANSCNT 


Return 
Type 


String 


String 
String 


String 


String 


String 


String 


‘String 


String 


String 
String 


Integer 
String 


Integer 
Integer 


Information Returned! 


TRUE or FALSE to indicate whether the device is 
a remote terminal for a SET HOST session from a 
remote node. 

TRUE or FALSE to indicate whether the device is a 
member that is the target of a full copy operation. 
TRUE or FALSE to indicate whether the device is a 
virtual unit. 

Device name of the virtual unit that represents 

the shadow set of which the specified device is a 
member. F$GETDVI returns a null string ("") if 
the specified device is not a member, or is itself a 
virtual unit. 

TRUE or FALSE to indicate whether the device is a 
shadow set member. 

TRUE or FALSE to indicate whether the device is a 
merge member of the shadow set. 

Device name of the next member in the shadow 
set. If you specify a virtual unit or a member, 
F$GETDVI returns the device name of members 

in random order. If you specify the name of a 
device that is neither a virtual unit nor a member, 
F$GETDVI returns a null string. 

F$GETDVI returns the device name of the next 
member in the shadow set even if the next member 
has been removed from the shadow set. 

The device name includes the allocation class if the 
allocation class is not zero; otherwise it includes 
the device name of the disk controller. 

TRUE or FALSE to indicate whether the device is 
shareable. 

TRUE or FALSE to indicate whether the device is 
being spooled. 


Name of the device being spooled. 


TRUE or FALSE to indicate whether the device is 
sequential block-oriented (that is, magnetic tape). 


Status information. 


_ TRUE or FALSE to indicate whether the device is 


software write-locked. 
Number of tracks per cylinder (disks only). 
Volume transaction count. 


lIn addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 


the system service $GETDVI. 
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Table DCLI-6 (Cont.) F$GETDVI Items 


item 
TRM 


TT ACCPORNAM 
TT ALTYPEAHD 


TT_ANSICRT 
TT_APP_KEYPAD 
TT_AUTOBAUD 


TT_AVO 


TT_BLOCK 


TT_BRDCSTMBX 


TT_CHARSET 
TT_CRFILL 
TT_CS_KANA 
TT_CS_KANJI 
TT_CS_HANZI 
TT_CS_HANGUL 
TT_CS_HANYU 
TT_CS_THAI 
TT_DECCRT 
TT_DECCRT2 


TT_DECCRTS3 


Return 
Type 
String 


String 
String 


String 
String 
String 


String 


String 
String 
Integer 
String 
String 
String 
String 
String 
String 
String 
String 
String 


String 


Lexical Functions 
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Information Returned’ 


TRUE or FALSE to indicate whether the device is a 
terminal. 

The terminal server name and port name. 

TRUE or FALSE to indicate whether the terminal 
has an alternate type-ahead buffer (terminals only). 
TRUE or FALSE to indicate whether the terminal 
is an ANSI CRT terminal (terminals only). 

TRUE or FALSE to indicate whether the keypad is 
in applications mode (terminals only). 

TRUE or FALSE to indicate whether the terminal 
has automatic baud rate detection (terminals only). 
TRUE or FALSE to indicate whether the terminal 
has a VT100-family terminal display (terminals 
only). 

TRUE or FALSE to indicate whether the terminal 
has block mode capability (terminals only). 

TRUE or FALSE to indicate whether the terminal 
uses mailbox broadcast messages (terminals only). 
A bitmap indicating the coded character set 
supported by the terminal. 

TRUE or FALSE to indicate whether the terminal 
requires fill after a carriage return (terminals only). 
TRUE or FALSE to indicate whether the terminal 
supports the DEC Kana coded character set. 
TRUE or FALSE to indicate whether the terminal 
supports the DEC Kanji coded character set. 
TRUE or FALSE to indicate whether the terminal 
supports the DEC Hanzi coded character set. 
TRUE or FALSE to indicate whether the terminal 
supports the DEC Korean coded character set. 
TRUE or FALSE to indicate whether the terminal 
supports the DEC Hanyu coded character set. 
TRUE or FALSE to indicate whether the terminal 
supports the DEC Thai coded character set. 

TRUE or FALSE to indicate whether the terminal 
is a Digital CRT terminal (terminals only). 

TRUE or FALSE to indicate whether the terminal 
is a Digital CRT2 terminal (terminals only). 


TRUE or FALSE to indicate whether the terminal 
is a Digital CRT3 terminal (terminals only). 


lfm addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by © 


the system service $GETDVI. 
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Table DCLI-6 (Cont.) FSGETDVI Items 


Return 
Item Type 
TT_DECCRT4 String 
TT_DIALUP String 
TT_DISCONNECT String 
TT_DMA String 
TT_DRCS String 
TT_EDIT String 
TT_EDITING String 
TT_EIGHTBIT String 
TT_ESCAPE String 
TT_FALLBACK String 
TT_HALFDUP String 
TT_HANGUP String 
TT_HOSTSYNC String 
TT_INSERT String 
TT_LFFILL String 
TT_LOCALECHO String 
TT_LOWER String 
TT_MBXDSABL String 


Information Returned’ 
TRUE or FALSE to indicate whether the terminal 
is a Digital CRT4 terminal (terminals only). 


TRUE or FALSE to indicate whether the terminal 
is connected to dialup (terminals only). 


TRUE or FALSE to indicate whether the terminal 


_ can be disconnected (terminals only). 


TRUE or FALSE to indicate whether the terminal 
has direct memory access (DMA) mode (terminals 
only). 

TRUE or FALSE to indicate whether the terminal 
supports loadable character fonts (terminals only). 
TRUE or FALSE to indicate whether the edit 
characteristic is set. 

TRUE or FALSE to indicate whether advanced 
editing is enabled (terminals only). 

TRUE or FALSE to indicate whether the terminal 
uses the 8-bit ASCII character set (terminals only). 
TRUE or FALSE to indicate whether the terminal 
generates escape sequences (terminals only). 
TRUE or FALSE to indicate whether the terminal 
uses the multinational fallback option (terminals 
only). 

TRUE or FALSE to indicate whether the terminal 
is in half-duplex mode (terminals only). 

TRUE or FALSE to indicate whether the hangup 
characteristic is set (terminals only). 

TRUE or FALSE to indicate whether the terminal 
has host/terminal communication (terminals only). 
TRUE or FALSE to indicate whether insert mode is 
the default line editing mode (terminals only). 
TRUE or FALSE to indicate whether the terminal 
requires fill after a line feed (terminals only). 
TRUE or FALSE to indicate whether the local echo 
characteristic is set (terminals only). 

TRUE or FALSE to indicate whether the terminal 
has the lowercase characters set (terminals only). 
TRUE or FALSE to indicate whether mailboxes 
associated with the terminal will receive unsolicited 


input notification or input notification (terminals 
only). 


1In addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 


the system service $GETDVI. 
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Table DCLI-6 (Cont.) F$GETDVI Items 


Item 
TT MECHFORM 


TT_MECHTAB 


TT_MODEM 

TT MODHANGUP 
TT_NOBRDCST 
TT_NOECHO 
TT_NOTYPEAHD 
TT_OPER 


TT_PAGE 
TT_PASTHRU 


TT_PHYDEVNAM 
TT_PRINTER 
TT_READSYNC 
TT_REGIS 
TT_REMOTE 
TT_SCOPE 
TT_SECURE 
TT_SETSPEED 
TT_SIXEL 


TT_SYSPWD 


Return 
Type 
String 


String 


String 
String 
String 
String 
String 
String 


Integer 
String 


String 


String 
String 
String 
String 
String 


String 


String 


String 


String 
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Information Returned’ 


TRUE or FALSE to indicate whether the terminal 
has mechanical form feed (terminals only). 


TRUE or FALSE to indicate whether the terminal 
has mechanical tabs and is capable of tab expansion 
(terminals only). 

TRUE or FALSE to indicate whether the terminal 
is connected to a modem (terminals only). 

TRUE or FALSE to indicate whether the modify 
hangup characteristic is set (terminals only). 
TRUE or FALSE to indicate whether the terminal 
will receive broadcast messages (terminals only). 
TRUE or FALSE to indicate whether the input 
characters are echoed. 

TRUE or FALS# to indicate whether data must be 
solicited by a read operation. 

TRUE or FALSE to indicate whether the terminal 
is an operator terminal (terminals only). 

Terminal page length (terminals only). 

TRUE or FALSE to indicate whether PASSALL 
mode with flow control is available (terminals only). 
Physical device name associated with a channel 
number or virtual terminal. 

TRUE or FALSE to indicate whether there is a 
printer port available (terminals only). 

TRUE or FALSE to indicate whether the terminal 
has read synchronization (terminals only). 

TRUE or FALSE to indicate whether the terminal 
has ReGIS graphics (terminals only). 

TRUE or FALSE to indicate whether the terminal 
has established modem control (terminals only). 
TRUE or FALSE to indicate whether the terminal 
is a video screen display (terminals only). 

TRUE or FALSE to indicate whether the terminal 
can recognize the secure server (terminals only). 
TRUE or FALSE to indicate whether you cannot set 
the speed on the terminal line (terminals only). 
TRUE or FALSE to indicate whether the sixel is 
supported (terminals only). 


TRUE or FALSE to indicate whether the system 
password is enabled for a particular terminal. 


1In addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 


the system service $GETDVI. 
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Table DCLI-6 (Cont.) FSGETDVI Items 


Return 

Item Type Information Returned’ 

TT TTSYNC String TRUE or FALSE to indicate whether there is 
terminal/host synchronization (terminals only). 

TT_WRAP String TRUE or FALSE to indicate whether a new line 

should be inserted if the cursor moves beyond the 

right margin. 

UNIT Integer The unit number. 

VOLCOUNT Integer The count of volumes in a volume set (disks only). 

VOLNAM String The volume name. | 

VOLNUMBER ' Integer Number of the current volume in a volume set 
(disks only). 

VOLSETMEM String TRUE or FALSE to indicate whether the device is a 
volume set (disks only). 

VPROT String The volume protection mask. 

WCK String TRUE or FALSE to indicate whether the device has 


write checking enabled. 


1In addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by 
the system service $GETDVI. 


Table DCLI-7 lists the values returned by the DEVCLASS item. 


Table DCLI-7 Values Returned by the DEVCLASS Item 


Value Device Class Symbolic Name 

1 Disk device DC$_DISK 

2 Tape device DC$_TAPE 

32 Synchronous communications device DC$_SCOM 

65 Card reader DC$_CARD 

66 Terminal DC$_TERM 

67 Line printer DC$_LP 

70 Workstation DC$_WORKSTATION 
96 Real-time DC$_REALTIME 

97 DECvoice DC$_DECVOICE 

128 Bus DC$_BUS 

160  ~ Mailbox DC$_ MAILBOX 

170 Remote console storage DC$_REMCSL_STORAGE 
200 Miscellaneous device DC$_MISC 


Table DCLI-8 lists the values returned by the DEVTYPE item. 
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Lexical Functions 
FSGETDVI 


Table DCLI-8 Values Returned by the DEVTYPE Item 


Value Device Type 
Device Class: DC$_DISK 
1 RK06 

2 RKO7 

3 — RPO4 

4 RP05 

5 RP06 

6 RMO03 

7 RP0O7 

8 RPO7HT 
9 RLO1 
10 RLO2 

11 RX02 
12 RX04 
13 RM80 
14 TU58 
15 RMO05 
16 RX01 
17 ML11 
18 RBO2 
19 RB80 
20 RA80_ 
21 RA81 
22 RA60 
23 RC25 
23 RZO1 
24 RZFO1 
24 RCF25 
25 RD51 
26 RX50 
27 RD52 
28 RD53 
29 RD26 
30 RA82 
31 RD31 
32 RD54 
33 CRX50 
34 RRD50 
35 GENERIC_DU 


Value 


54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 


68 . 


69 
70 
71 
71 
72 
72 
73 
74 
75 
76 
77 
78 
79 
80 
80 
81 
82 
83 
83 
84 
85 
86 


Device Type 


GENERIC_DK 
RX23 

RF31 

RF72 
RAM_DISK 
RZ25 

RZ56 

RZ57 
RX238S 
RX338 
RAQ2 
SSTRIPE 
RZ23L 
RX26 
RZ571 
RZ31 

RZ58 
SCSI-MO 
RWZO01 
LO_COST_CD 
RRD42 
CD_LOADER 1 
ESE25 
RFH31 
RFH72 
FR73 
RFH73 
RA72— 
RA71 
RAH72 
RF32 
RFH32 
RFF31 
RF31F 
RZ72 

RZ73 

RZ35 


(continued on next page) 


DCLI-335 


Lexical Functions 
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Table DCLI-8 (Cont.) Values Returned by the DEVTYPE Item 


Value 


36 
37 
38 
39 
40 
41 
42 
43 
44 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 


Device Type 
Device Class: DC$_DISK 


RX33 
RX18 
RA70 
RA90 
RD32 
DISK9 
RX35 
RF30 
RF70 
RF71 
RD383 
ESE20 
TU56 
RZ22 
RZ23 
RZ24 
RZ55 
RRD40 
RRD40 


Value 


87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
129 
130 
131 
132 
133 
134 


Device Type 


RZ24L 
RZ25L 
RZ55L 
RZ56L 
RZ57L 
RA73 
RZ26 
RZ36 
RZ74 
ESE52 
ESE56 
ESE58 
FD1 
FD2 
FD3 
FD4 | 
FD5 
FD6 
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Table DCLI-8 (Cont.) Values Returned by the DEVTYPE Item 


Value Device Type 
Device Class: DC$_TAPE 
dl, TE16 

2 TU45 

3 TU77 

4 TS11 

5 TU78 

6 TA78 

7 TU80 

8 TU81 

9 TA81 

10 TK50 

11 MR_TU70 
12 MR_TU72 © 
13 MW_TSU05 
14 MW_TSV05 
15 TK70 

16 RV20 

16 RV80 

17 TK60 

18 GENERIC_TU 
19 TA79 

20 TAPE9 

21 TA90 

22 TF30 

23 TF70 


FSGETDVI 
Value Device Type 
24 RV60 
25 -'TZ30 
26 TM32 
27 TZXO 
27 TSZ05 
28 GENERIC_MK 
29 TK508S 
30 TZ30S 
31 TK70L 
32 TLZ04 
33 TZK10 
34 TSZ07 
35 TSZ08 
36 TASOE 
37 TZK11 
38 TZ85 
39 TZ86 
40 TZ87 
Al TZ857 
42 EXABYTE 
43 TAPE_LOADER_1 
44 TAQ1 
45 TLZ06 
46 TA85 


(continued on next page) 
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Lexical Functions 
FSGETDVI 


Table DCLI-8 (Cont.) Values Returned by the DEVTYPE Item 


Value Device Type 
Device Class: DC$_SCOM 
1 DMC11 

2 DMR11 

3 XK_3271 

4 XJ_2780 

5 NW_X25 

6 NV_X29 

7 SB_ISB11 

8 MX_MUX200 
9 DMP11 

10 DMF32 

11 XV_3271 

12 CI 

13 NI 

14 UNAI1 

14 DEUNA 

15 YN_X25 

16 YO_X25 

17 YP_ADCCP 
18 YQ 3271 

19 YR_DDCMP 
20 YS_SDLC 
21 UK_KTC32 
22 DEQNA 

23 DMV11 

24 ES_LANCE 
25 DELUA 

26 NQ_3271 


Device Class: DC$_CARD 
1 CR11 
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Value 


27 
28 
29 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 


48 


49 
50 
51 


Device Type 


DMB32 
YI_KMS11K 
ET_DEBNT 
ET_DEBNA 
SJ_DSV11 
SL_DSB32 
ZS_DST32 
XQ_DELQA 
ET_DEBNI 
EZ_SGEC 
EX_DEMNA 
DIV32 
ZQ_DEQTA 
FT_NI 
EP_LANCE 
KWV32 
SM_DSF32 
FX_DEMFA 
SF_DSF32 
SE_DUP11 
SE_DPV11 
ZT_DSW 
FC_DEFZA 
EC_PMAD 
EZ_TGEC 
EA_DEANA 


(continued on next page) 
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Table DCLI-8 (Cont.) Values Returned by the DEVTYPE Item 


Value Device Type 
Device Class: DC$_TERM 
07 TTYUNKN 
1 VT05 

2 VK100 

3 VT173 

4 TQ BTS 
10 TEK401X 
16 FT1 

17 FT2 
18 FT3 

19 FT4 

20 FT5 

21 FT6 

22 FT7 

23 FT8 

32 LAX 

33 LA36 

33 LA120 

34 LA34 

35 LA38 

36 LA12 

37 LA24 

37 LA100 

38 LQP02 

40 LA210 

Al LNO3 


Device Class: DC$_LP 


1 LP11 

2 LA11 

3 LA180 

4 LC_DMF32 


Device Class: DC$ WORKSTATION 


1 VAXstation 100 
2 VAXstation 125 
3 VAXstation 8200 


Value 


42 
43 
64 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
96 
97 
98 
99 
100 
101 
102 
110 
111 
112 
113 


oO 


Device Type 


LNO1K 

LA80 

VT5X 

VT52 

VT55 

DZ11 

DZ32 

DZ730 
DMZ32 

DHV 

DHU 

SLU 

TERM9 

LAT 

VT100 

VT101 

VT102 

VT105 

VT125 

VT131 

VT132 
VT200_Series 
Pro_Series 
VT300_Series 
VT400_Series 


LI_DMB32 
PRTR9Y 
SCSI_LSCANNER_1 


VAXstation virtual device 
DECW output device 
DECW input device 


(continued on next page) 
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Lexical Functions 
FSGETDVI 


Table DCLI-8 (Cont.) Values Returned by the DEVTYPE Item 


Value Device Type Value Device Type 
Device Class: DC$_REALTIME 

1 LPA11 9 XP_PCL11B 

2 DR780 10 IX_IEX11 

3 DR750 11 FP_FEPCM 

4 DR11W 12 TK_FCM 

5 PCL11R 13 XI_DR11C 

6 PCL11T 14 XA_DRV11WA 
7 DR11C 15 DRB32 

8 XI_DR11C 16 HX_DRQ3B 


Device Class: DC$_DECVOICE 


1 | VQ class driver 3 VM M3135 port driver 
2 VX M7132 port driver 4 VN M3136 port driver 


Device Class: DC$_BUS 


1 C1780 21 BSA 

2 C1750 21 KSB50 
3 UQPORT 22 TK709 
3 UDA50 23 RV20P 
4 UDA50A 23 RV80P 
5 LESI 24 TK60P 
6 TU81P 25 SII 
RDRX 26 KFSQSA 
8 TK50P 26 KFQSA 
9 RUX50P 27 SHAC 
10 RC26P 28 CIXCA 
ra QDA5O 29 CIXCB 
iB KDA50 30 SCSII 
12 BDAS5O 31 HSX50 
12 KDB50 31 KDM70 
13 RRD50P 32 TM32P 
14 QDA25 33 TK7LP 
14 KDA25 34 SWIFT 
15 BC1750 35 N53C94 
16 BCA 36 KFMSA 
17 RQDX3 37 SCSI_XTENDR 


(continued on next page) 
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Lexical Functions 
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Table DCLI-8 (Cont.) Values Returned by the DEVTYPE Item 


Value Device Type Value 


Device Class: DC$_BUS 


18 NISCA  — 38 
19 AIO 39 
19 KFBTA 40 
20 AIE 41 
20, DEBNT 


Device Class: DC$_MAILBOX 


1 MBX . 3 
2 SHRMBX 4 


Device Class: DC$_REMCSL_STORAGE 


DAP- 1 
accessed 
device 


Device Class: DC$_MISC . 


1 DN11 
2 PV 


mm Co 


$ ERR = FSGETDVI(" DQA0", "ERRCNT") 
$ SHOW SYMBOL ERR 
ERR = 0 Hex = 00000000 Octal = 000000 


Device Type 


FT_TRACE_RAM 
XVIB 

XZA_SCSI 
XZA_DSSI 


NULL 
PIPE © 


SFUNS 
USER9 


This example shows how to use the F$GETDVI function to return an error count 
for the device DQAO. You must place quotation marks (“”) around the device 
name DQAO and the item ERRCNT because they are string literals. 
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Lexical Functions 


FSGETUPI 


FSGETUJPI 


Format 


Returns information about the specified process. 


Requires GROUP privilege to obtain information on other processes in 
the same group. Requires WORLD privilege to obtain information on any 
other processes in the system. 


F$GETUJPI(pid,item) 


Return Value 


Arguments 


Description 
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Hither an integer or a character string, depending on the item you request. 
Table DCLI-9 shows the data types of the values returned for each item. 


pid 

Specifies the process identification (PID) number of the process for which 
information is being reported. Specify the pid argument as a character string 
expression. You can omit the leading zeros. 


nett 


If you specify a null string (""), the current PID number is used. 


You cannot use an asterisk (*) or percent sign (%) wildcard character to specify 
the pid argument in the F$GETJPI function, as you can with the $GETJPI 
system service. To get a list of process identification numbers, use the F$PID 
function. 


item 

Indicates the type of process information to be returned. Specify the item 
argument as a character string expression. You can specify any one of the items 
listed in Table DCLI-9. 


The F$GETJPI lexical function invokes the $GETJPI system service to return 
information about the specified process. The function returns information on 
all items that can be specified with the $GETJPI system service. For more 
information on the $GETJPI system service, see the OpenVMS System Services 


- Reference Manual. 


You can use the F$GETJPI lexical function to find out whether a process 
automatically unshelves files. 


When you specify the STS2 item code, FSGETJPI returns a 32-bit numeric value. 
When you convert this numeric value to binary format, the digit at symbolic bit 
position PCB$V_NOUNSHELVE shows you the process unshelving default. If the 
bit is 1, automatic unshelving is turned off; if 0, automatic unshelving is turned 
on. 


Table DCLI-9 lists the items you can specify with the F$GETJPI function, the 
information returned, and the data type of this information. 


Table DCLI-9 FSGETJPI Items 


Item 


ACCOUNT 


APTCNT 
ASTACT 


ASTCNT 
ASTEN 
ASTLM 
AUTHPRI 


AUTHPRIV 


BIOCNT 
BIOLM 
BUFIO 
BYTCNT 


BYTLM 
CLINAME 


CPULIM 
CPUTIM 


CREPRC_FLAGS 


CURPRIV 
DFPFC 
DFWSCNT 
DIOCNT 
DIOLM 
DIRIO 


EFCS 
EFCU 
EFWM 
ENQCNT 
ENQLM 


Return 
Type 


String 


Integer 
Integer 


Integer 
Integer 
Integer 
Integer 


String 


Integer 


Integer 
Integer 
Integer 


Integer 
String 


Integer 
Integer 


Integer 


String 

Integer 
Integer 
Integer 
Integer 
Integer 


Integer 
Integer 
Integer 
Integer 
Integer 


Lexical Functions 
FSGETUJPI 


Information Returned 

Account name string (8 characters filled 
with trailing blanks). 

Active page table count. 


Access modes with active asynchronous 
system traps (ASTs). 


Remaining AST quota. 
Access modes with ASTs enabled. 
AST limit quota. 


Maximum priority that a process 
without the ALTPRI (alter priority) 
privilege can achieve with the $SETPRI 
system service. 


Privileges that a process is authorized to 
enable. 


Remaining buffered I/O quota. 
Buffered I/O limit quota. 
Count of process buffered I/O operations. 


Remaining buffered I/O byte count 
quota. 


Buffered I/O byte count quota. 


Current command language interpreter; 
always returns DCL. 


Limit on process CPU time. 


CPU time used in hundredths of a 
second. 


Flags specified by the stsflg argument 
in the $CREPRC call that created the 
process. . 


Current process privileges. 
Default page fault cluster size. 
Default working set size. 
Remaining direct I/O quota. 
Direct I/O limit quota. 


Count of direct I/O operations for the 
process. 


Local event flags 0-31. 

Local event flags 32-63. 
Event flag wait mask. 

Lock request quota remaining. 
Lock request quota limit. 


- (continued on next page) 
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Table DCLI-9 (Cont.) FSGETJPI Items 


Return 

Item Type Information Returned 

EXCVEC - Integer Address of a list of exception vectors. 

FAST_VP_SWITCH Integer Number of times this process has issued 
a vector instruction that enabled an 
inactive vector processor without the 
expense of a vector context switch. 

FILCNT Integer Remaining open file quota. 

FILLM _ Integer Open file quota. 

FINALEXC Integer Address of a list of final exception 

. vectors. 

FREPOVA Integer First free page at end of program region 
(PO space) (irrelevant if no image is 
running). 

FREP1VA Integer First free page at end of control region 
(P1 space). 

FREPTECNT Integer Number of pages available for virtual 
memory expansion. 

GPGCNT Integer Global page count in working set. 

GRP Integer | Group number of the user identification 
code (UIC). 

IMAGECOUNT Integer Number of images that have been run 

. down for the process. 

IMAGNAME String File name of the current image. 

IMAGPRIV String Privileges with which the current image 
was installed. 

JOBPRCCNT Integer Number of subprocesses owned by the 
job. | 

JOBTYPE Integer Execution mode of the process at the 
root of the job tree. 

LAST_LOGIN_I String Time of your last interactive login (the 
value that was reported when you logged 
in). 

LAST _LOGIN_N String © Time of your last noninteractive login 
(the value that was reported when you 
logged in). 

LOGIN_FAILURES Integer Number of login failures that occurred 
prior to the start of the current session 
(the value that was reported when you 

| logged in). 
LOGIN_FLAGS Integer A longword bitmask that contains 


additional information relating to the 
login sequence. 


LOGINTIM String Process creation time. 


(continued on next page) 
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Table DCLI-9 (Cont.) F$GETJPI Items 


Item 


-MASTER_PID 


MAXDETACH 


MAXJOBS 


MEM 
MODE 


MSGMASK 
NODENAME 


NODE_CSID 


NODE_VERSION 


OWNER 


PAGEFLTS 
PAGFILCNT 
PAGFILLOC 
PGFLQUOTA 


PHDFLAGS 
PID 
PPGCNT 
PRCCNT 


PRCLM 

PRCNAM 

PRI 

PRIB 
PROC_INDEX 
PROCESS_RIGHTS 


Return 
Type 


String 


Integer 


Integer 


Integer 
String 


Integer 
String 


Integer 


String 


String 


Integer 
Integer 
Integer 
Integer 


Integer 
String 

Integer 
Integer 


Integer 
String 
Integer 
Integer 
Integer 
String 


Lexical Functions 
FSGETJPI 


Information Returned 


Process identification (PID) number of 
the process at the top of the current job’s 
process tree. 


Maximum number of detached processes 
allowed the user who owns the process. 


Maximum number of active processes 
allowed for the user who owns the 
process. 


Member number of the UIC. 


Current process mode (BATCH, 
INTERACTIVE, NETWORK, or 
OTHER). . 


Default message mask. 


The name of the VMScluster node on 
which the process is running. 


Cluster ID of the VMScluster node on 
which the process is running. 


Operating system version number of the 
VMScluster node on which the process is 
running. 

Process identification number of process 
owner. 

Count of page faults. 

Remaining paging file quota. 

Location of the paging file. 

Paging file quota (maximum virtual page 
count). 

Flags word. 

Process identification number. 

Process page count. 


Number of subprocesses owned by the 
process. 


Subprocess quota. 
Process name. | 
Process’s current priority. 
Process’s base priority. 
Process’s index number. 


The contents of the process’s local rights 
list, including your UIC. This item 

code returns a list of identifier names 
separated by commas (, ). 


(continued on next page) 
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Table DCLI-9 (Cont.) F$GETJPI Items 


Return 
Item Type Information Returned 
PROCPRIV String Process’s default privileges. 
RIGHTSLIST String» The contents of all of the process rights 


lists; the equivalent of PROCESS_ 
RIGHTS plus SYSTEM_RIGHTS. This 
item code returns a list of identifier 
names separated by commas. 
RIGHTS_SIZE Integer Number of bytes required to buffer the 
rights list. The rights list includes both 
the system rights list and the process 


rights list. . 

SHRFILLM Integer Maximum number of open shared files 
allowed for the job to which the process 
belongs. 

SITESPEC Integer Per-process site-specific longword. 

SLOW_VP_SWITCH Integer Number of times this process has issued 


a vector instruction that enabled an 
inactive vector processor with a full 
vector context switch. 


STATE String Process state. 

STS Integer First longword of process status flags. 
STS2 Integer Second longword of process status flags. 
SWPFILLOC Integer Location of the swap file. 
SYSTEM_RIGHTS String The contents of the system rights list 


for the process. This item code returns 
a list of identifier names separated by 


commas. 

TABLENAME String File specification of the process’s current 
command language interpreter (CLI 
table. 

TERMINAL String Login terminal name for interactive 
users (1—7 characters). 

TMBU Integer Termination mailbox unit number. 

TQCNT Integer Remaining timer queue entry quota. 

TQLM Integer Timer queue entry quota. 

TT_ACCPORNAM String Access port name for the terminal 
associated with the process. 

TT_PHYDEVNAM String Physical device name of the terminal 
associated with the process. 


UAF_FLAGS Integer User authorization file (UAF) flags from 
the UAF record of the user who owns 
the process. 


UIC String Process’s user identification code (UIC). 


(continued on next page) 
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Table DCLI-9 (Cont.) FSGETJPI Items 


Item 


USERNAME 


VIRTPEAK 
VOLUMES 
VP_CONSUMER 


VP_CPUTIM 


WSAUTH 
WSAUTHEXT 


WSEXTENT 
WSPEAK 
WSQUOTA 
WSSIZE 


Return 
Type 


String 


Integer 
Integer 
Boolean 


Integer 


Integer 
Integer 


Integer 
Integer 
Integer 
Integer 


Lexical Functions 
FSGETUJPI 


Information Returned 


User name string (12 characters filled 
with trailing blanks). 


Peak virtual address size. 
Count of currently mounted volumes. 


Flag indicating whether the process is a 
vector consumer. 


Total amount of time the process has 
accumulated as a vector customer. 


Maximum authorized working set size. 


Maximum authorized working set 
extent. 


Current working set extent. 
Working set peak. 

Working set size quota. 

Process’s current working set size. 


If you use the F$GETJPI function to request information on the null process or 
the swapper process, you can specify any of the items in Table DCLI-9 except the 


following: 


ACCOUNT 
EXCVEC 
IMAGNAME _ 
PGFLQUOTA 
SITESPEC 
VIRTPEAK 


$ NAME = FSGETJPI("3B0018", "USERNAME" ) 
$ SHOW SYMBOL NAME 


NAME = "JANE" 


LOGINTIM 
PRCCNT 


VOLUMES 


ENQCNT ENQLM 
FILM FINALEXC 
MSGMASK PAGFILCNT 
PRCLM PROCPRIV 
TQLM USERNAME 
WSPEAK 


This example shows how to use the F$GETJPI function to return the user name 
for the process number 3B0018. The user name is assigned to the symbol NAME. 
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Lexical Functions 


FS$GETQUI 


FSGETQUI 


Format 


Returns information about queues, including batch and print jobs currently in 
the queues, form definitions, and characteristic definitions kept in the queue 
database. 


Also returns information about queue managers. 


For most operations, read (R) access is required. 


FSEGETQUI|(function, [item], [object-id],[flags]) 


Return Value 


Arguments 


Function 


Either an integer or a character string, depending on the item you request. For 
items that return a Boolean value, the string is TRUE or FALSE. If the $GETQUI 
system service returns an error code, FSGETQUI returns a null string (""). 


function 

Specifies the action that the F$GETQUI lexical function is to perform. 
F$GETQUI supports all functions that can be specified with the $GETQUI 
system service. The following table lists these functions: 


Description 


CANCEL_OPERATION - Terminates any wildcard operation that may have been 


initiated by a previous call to FSGETQUI. 


DISPLAY_CHARACTERISTIC Returns information about a specific characteristic definition 


or the next characteristic definition in a wildcard operation. 


DISPLAY_ENTRY Returns information about a specific job entry or the next 


job entry that matches the selection criteria in a wildcard 
operation. The DISPLAY_ENTRY function code is similar 
to the DISPLAY_JOB function code in that both return job 
information. DISPLAY_JOB, however, requires that a call 
be made to establish queue context; DISPLAY_ENTRY does 
not require that queue context be established. Only those 
entries that match the user-name of the current process will 
be processed. 


DISPLAY_FILE Returns information about the next file defined for the 


current job context. Before you make a call to FSGETQUI 
to request file information, you must make a call to display 
queue and job information (with the DISPLAY_QUEUE 
and DISPLAY_JOB function codes) or to display entry 
information (with the DISPLAY_ENTRY function code). 


DISPLAY_FORM Returns information about a specific form definition or the 
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next form definition in a wildcard operation. 


Function 


DISPLAY_JOB 


Lexical Functions 
FSGETQUI 


Description 


Returns information about the next job defined for 

the current queue context. Before you make a call to 
F$GETQUI to request job information, you must make 

a call to display queue information (with the DISPLAY_ 
QUEUE function code). The DISPLAY_JOB function code is 
similar to the DISPLAY_ENTRY function code in that both 
return job information. DISPLAY_JOB, however, requires 
that a call be made to establish queue context; DISPLAY_ 
ENTRY does not require that queue context be established. 


DISPLAY_MANAGER Returns information about a specific queue manager or the 


next queue manager in a wildcard operation. 


DISPLAY_QUEUE Returns information about a specific queue definition or the 


next queue definition in a wildcard operation. 


TRANSLATE QUEUE Translates a logical name for a queue to the equivalence 


Function 


name for the queue. 


Some function arguments cannot be specified with the item-code, the object-id, 
or the flags argument. The following table lists each function argument and 
corresponding format line to show whether the item-code, object-id and flags 
arguments are required, optional, or not applicable for that specific function. 

In the following format lines, brackets ([ ]) denote an optional argument. An 
omitted argument means the argument is not applicable for that function. Note 
that two commas (,,) must be used as placeholders to denote an omitted (whether 
optional or not applicable) argument. 


Format Line 


CANCEL_OPERATION F$GETQUI(“CANCEL_OPERATION”) or F$GETQUI(“ ”) 


DISPLAY_ FEGETQUICDISPLAY_CHARACTERISTIC”, [item],object- 
CHARACTERISTIC id,[flags]) . 
DISPLAY_ENTRY FEGETQUI(“DISPLAY_ENTRY”,[item], [object-id],[flags]) 
DISPLAY_FILE FEGETQUI(“DISPLAY_FILE” [item],,[flags]) 
DISPLAY_FORM FEGETQUI(“DISPLAY_FORM” [item], object-id,[flags]) | 
DISPLAY_JOB FSGETQUI(“DISPLAY_JOB’ [item],,[flags]) 
DISPLAY_MANAGER FEGETQUI("DISPLAY_MANAGER'" [item], object-id,[flags]) 
DISPLAY_QUEUE FEGETQUI(“DISPLAY_QUEUE” [item], object-id,[flags]) 


TRANSLATE_QUEUE F$GETQUI(“TRANSLATE_QUEUE” [item], object-id) 


item 

Corresponds to a $GETQUI system service output item code. The item argument 
specifies the kind of information you want returned about a particular queue, 
job, file, form, or characteristic. On VAX, queue manager information is also 
available. Table DCLI—11 lists each item code and the data type of the value 
returned for each item code. 


object-id 

Corresponds to the $GETQUI system service QUISSEARCH_NAME, QUI$_ 
SEARCH_NUMBRR, and QUI$_SEARCH_JOB_NAME input item codes. 
The object-id argument specifies either the name or the number of an object 
(for example, a specific queue name, job name, or form number) about which 
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Lexical Functions 
| FSGETQUI . 


F$GETQUI is to return information. The asterisk (*) and the percent sign (%) 
wildcard characters are allowed for the following functions: 


DISPLAY_CHARACTERISTIC 
DISPLAY_ENTRY 
DISPLAY_FORM 
DISPLAY_MANAGER 
DISPLAY_QUEUE 


By specifying an asterisk (*) or percent sign (%) wildcard character as the 
object-id argument on successive calls, you can get status information about 
one or more jobs in a specific queue or about files within jobs in a specific queue. 
When a name is used with wildcard characters, each call returns information for 


the next object (queue, form, and so on) in the list. A null string ( 


tt 


) is returned 


when the end of the list is reached. A wildcard can represent only object names, 
not object numbers. 


flags 


Specifies a list of keywords, separated by commas, that corresponds to the flags 
defined for the $GETQUI system service QUI$_SEARCH_FLAGS input item 
code. (These flags are used to define the scope of the object search specified in the 
call to the $GETQUI system service.) Note that keywords in Table DCLI-10 can 
be used only with certain function codes. 


Table DCLI-10 FSGETQUI Keywords 


Keyword 
ALL_JOBS 


BATCH 
EXECUTING_JOBS 


FREEZE_CONTEXT: 


GENERIC 


HOLDING. JOBS 


DCLI-350 


Valid Function Code 
DISPLAY_JOB 


DISPLAY_QUEUE 
DISPLAY_ENTRY 


DISPLAY_ENTRY DISPLAY_ 
JOB 


DISPLAY_ 
CHARACTERISTIC 
DISPLAY_ENTRY 
DISPLAY_FILE 
DISPLAY_FORM 
DISPLAY_JOB 
DISPLAY_MANAGER 
DISPLAY_QUEUE 


DISPLAY_ENTRY DISPLAY_ 
QUEUE 


DISPLAY_ENTRY DISPLAY_ 
JOB 


Description 


Requests that F$SGETQUI search 
all jobs included in the established 
queue context. If you do not specify 
this flag, FSGETQUI returns 
information only about jobs that 
have the same user name as the 
caller. 


Selects batch queues. 
Selects executing jobs. 


When in wildcard mode, prevents 
advance of wildcard context to the 
next object. If you do not specify 
this flag, the context is advanced to 
the next object. 


Selects generic queues for 
searching. . 


Selects jobs on unconditional hold. 


(continued on next page) 


Table DCLI-10 (Cont.) FS$GETQUI Keywords | 


Keyword 
PENDING_JOBS 


PRINTER 
RETAINED_JOBS 
SERVER 


-SYMBIONT 


TERMINAL 


THIS_JOB 


TIMED_RELEASE_JOBS 


WILDCARD 


Description 


Valid Function Code 


DISPLAY_ENTRY DISPLAY_ 
JOB 


DISPLAY_QUEUE 
DISPLAY_ENTRY 


DISPLAY_ENTRY DISPLAY_ 
JOB 


DISPLAY_QUEUE 
DISPLAY_ENTRY 


DISPLAY_QUEUE 
DISPLAY ENTRY 


DISPLAY_QUEUE 
DISPLAY_ENTRY 


DISPLAY_FILE DISPLAY_ 
JOB DISPLAY_QUEUE 


DISPLAY_ENTRY DISPLAY_ 
JOB 


DISPLAY_ 
CHARACTERISTIC 
DISPLAY ENTRY 
DISPLAY _FORM 
DISPLAY MANAGER | 
DISPLAY_QUEUE 


Lexical Functions 
FSGETQUI 


Description 


Selects pending jobs. 
Selects printer queues. 
Selects jobs being retained. 
Selects server queues. 


Selects all output queues. 
Equivalent to specifying 
“PRINTER,SERVER,TERMINAL”. 


Selects terminal queues. 


Selects all job file information 
about the calling batch job, the 
command file being executed, or 
the queue associated with the 
calling batch job. 


Selects jobs on hold until a 
specified time. 

Establishes and saves a context. 
Because the context is saved, the 
next operation can be performed 
based on that context. 


The F$GETQUI lexical function invokes the $GETQUI system service to return 
information about queues, batch and print jobs currently in those queues, form 
definitions, and characteristic definitions kept in the system job queue file. The 
F$GETQUI lexical function provides all the features of the $GETQUI system 
service, including wildcard and nested wildcard operations. For example, in 
nested wildcard operations, $GETQUI returns information about objects defined 
within another object. Specifically, this mode allows you to query jobs contained 
in a selected queue or files contained in a selected job in a sequence of calls. After 
each call, the system saves the GQC (internal GETQUI context block) so that 
the GQC can provide the queue or job context necessary for subsequent calls. 
For more information, see the description of the $GETQUI system service in the 


OpenVMS System Services Reference Manual. 


The F$GETQUI function returns information on all items that can be specified 
with the $GETQUI system service. Table DCLI-—11 lists the items you can specify 
with the FSGETQUI function, the information returned, and the data type of this 


information. 


DCLI-351 


Lexical Functions 
FSGETQUI 


Table DCLI-11 FSGETQUI Items 


Return 
Item Type 
ACCOUNT_NAME! String 
AFTER_TIME String 


ASSIGNED_QUEUE_NAME! String 


AUTOSTART_ON String 
BASE_PRIORITY Integer 
CHARACTERISTICS! String 
CHARACTERISTIC_NAME String 
CHARACTERISTIC_NUMBER Integer 
CHECKPOINT_DATA! String 
CLI! String 
COMPLETED_BLOCKS Integer 
CONDITION_VECTOR! Integer 
CPU_DEFAULT String 
CPU_LIMIT! String 
DEFAULT_FORM_NAME String 
DEFAULT_FORM_STOCK String 


Information Returned 


The account name of the owner of the specified 
job. 

The system time at or after which the specified 
job can execute. 


The name of the execution queue to which the 
logical queue specified in the call to FSGETQUI 
is assigned. . 

A list of nodes or node device pairs indicating 
where the queue can start. 


The priority at which batch jobs are initiated 
from a batch execution queue or the priority of a 
symbiont process that controls output execution 
queues. 


_ The characteristics associated with the specified 


queue or job. 
The name of the specified characteristic. 
The number of the specified characteristic. 


The value of the DCL symbol BATCH$RESTART 
when the specified batch job is restarted. 


The name of the command language interpreter 
(CLD used to execute the specified batch job. 
The file specification returned assumes the 
device name SYS$SYSTEM and the file type 
EXE. 

The number of blocks that the symbiont has 
processed for the specified print job. This item 
code is applicable only to print jobs. 

The completion status of the specified job. 

The default CPU time limit specified for the 
queue in delta time. This item code is applicable 
only to batch execution queues. 

The maximum CPU time limit specified for the 
specified job or queue in delta time. This item 
code is applicable only to batch jobs and batch 
execution queues. 

The name of the default form associated with 
the specified output queue. . 

The name of the paper stock on which the 
specified default form is to be printed. 


TRequires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 
DEVICE_NAME 


ENTRY_NUMBER 
EXECUTING_JOB_COUNT 


FILE_BURST 
FILE_CHECKPOINTED! 


FILE_COPIES! 


FILE_COPIES_DONE! 


FILE_COUNT 
FILE_DELETE 
FILE_DOUBLE_SPACE 
FILE_EXECUTING! 


FILE_FLAG 


Return 
Type 


String 


Integer 
Integer 


String 
String 


Integer 


Integer 


Integer 
String 
String 
String 


String 


Lexical Functions 
FSGETQUI 


Information Returned 


The node and device (or both) on which the 
specified execution queue is located. For output 
execution queues, only the device name is 
returned. The node name is used only in dual- 
architecture VMScluster systems. The node 
name is specified by the system parameter 
SCSNODE for the processor on which the queue 
executes. 

For batch execution queues, a null string ("" ) is 
returned. To get the name of the node on which 
a batch queue is executing, use the SCSNODE_ 
NAME item. 


The queue entry number of the specified job. 


ete 


The number of jobs in the queue that are 
currently executing. 

TRUE or FALSE to indicate whether burst and 
flag pages are to be printed preceding a file. 
TRUE or FALSE to indicate whether the 
specified file is checkpointed. 

The number of times the specified file is to be 
processed. This item code is applicable only to 
output execution queues. 

The number of times the specified file has been 
processed. This item code is applicable only to 
output execution queues. 

The number of files in a specified job. 

TRUE or FALSE to indicate whether the 
specified file is to be deleted after execution 

of request. 

TRUE or FALSE to indicate whether the 
symbiont formats the file with double spacing. 
TRUE or FALSE to indicate whether the 
specified file is being processed. 

TRUE or FALSE to indicate whether a flag page 
is to be printed preceding a file. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 


(continued on next page) 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 
FILE_FLAGS! 


FILE_IDENTIFICATION! 


FILE_PAGE_HEADER 


FILE_PAGINATE 


FILE_PASSALL 


FILE_SETUP_MODULES! 


FILE_SPECIFICATION! 


Return 
Type 


Integer 


String 


String 


String 


String 


String 


String 


Information Returned 


The processing options that have been selected 
for the specified file. The integer represents a 

bit field. To find the settings of each bit in the 
field, use one of the following items in place of 
FILE_FLAGS: 


FILE_BURST 
FILE_DELETE 
FILE_DOUBLE_SPACE 
FILE_FLAG 
FILE_PAGE_HEADER 
FILE_PAGINATE 
FILE_PASSALL 
FILE_TRAILER 


The internal file-identification value that 
uniquely identifies the selected file. This 
value specifies (in order) the following three 
file-identification fields in the RMS NAM block: 


NAM$T_DVI (16 bytes) 
NAM$W_FID (6 bytes) 
NAM$W_DID (6 bytes) 


TRUE or FALSE to indicate whether a page 
header is to be printed on each page of output. 


TRUE or FALSE to indicate whether the 
symbiont paginates output by inserting a form 
feed whenever output reaches the bottom margin 
of the form. 


TRUE or FALSE to indicate whether the 
symbiont prints the file in PASSALL mode. 


The names of the text modules that are to be 
extracted from the device control library and 
copied to the printer before the specified file is 
printed. This item code is meaningful only for 
output execution queues. 

The fully qualified RMS file specification of 


the file about which FSGETQUI is returning 
information. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 
FILE_STATUS! 


FILE_TRAILER 


FIRST_PAGE! 


FORM_DESCRIPTION 


FORM_FLAGS 


FORM_LENGTH 
FORM_MARGIN_BOTTOM 
FORM_MARGIN_LEFT 
FORM_MARGIN_RIGHT 


FORM_MARGIN_TOP 
FORM NAME! 


FORM_NUMBER 
FORM_SETUP_MODULES 


Return 
Type 


Integer 


String 


Integer 


String 


Integer 


Integer 
Integer 
Integer 
Integer 


Integer 
String 


Integer 
String 


Lexical Functions 
FSGETQUI 


Information Returned 


File status information. The integer represents 
a bit field. To find the settings of each bit in the 
field, use one of the following items in place of 
FILE_STATUS: 


FILE_CHECKPOINTED 
FILE_EXECUTING 


TRUE or FALSE to indicate whether a trailer 
page is to be printed following a file. 


The page number at which the printing of the 
specified file is to begin. This item code is 
applicable only to output execution queues. 


The text string that describes the specified form 
to users and operators. 


The processing options that have been selected 
for the specified form. The integer represents a 
bit field. To find the settings of each bit in the 

field, use one of the following items in place of 

FORM_FLAGS: 


FORM_SHEET_FEED 
FORM_TRUNCATE 
FORM_WRAP 


The physical length of the specified form in 
lines. This item code is applicable only to output 
execution queues. 


The bottom margin of the specified form in lines. 


The left margin of the specified form in 
characters. 

The right margin of the specified form in 
characters. | 

The top margin of the specified form in lines. 
The name of the specified form or the mounted 
form associated with the specified job or queue. 
The number of the specified form. 

The names of the text modules that are to be 
extracted from the device control library and 
copied to the printer before a file is printed on 
the specified form. This item code is meaningful 
only for output execution queues. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 


(continued on next page) 
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Table DCLI-11 (Cont.) F$GETQUI Items 


item 
FORM _SHEET_FEED 


FORM_STOCK} 
FORM_TRUNCATE 


FORM_WIDTH 
FORM_WRAP 


GENERIC_TARGET 


HOLDING_JOB_COUNT 


INTERVENING_BLOCKS 


INTERVENING_JOBS 


JOB_ABORTING 
JOB_COMPLETION_QUEUE! 
JOB_COMPLETION_TIME! 
JOB_COPIES! 
JOB_COPIES_DONE! 


JOB_CPU_LIMIT! 


Return 


Type 
String 


String 
String 


Integer 
String 


String 


Integer 


Integer 


Integer 


String 
String 
String 
Integer 
integer 


String 


Information Returned 


TRUE or FALSE to indicate whether the 
symbiont pauses at the end of each physical 
page so that another sheet of paper can be 
inserted. 


The name of the paper stock on which the 
specified form is to be printed. 


TRUE or FALSE to indicate whether the printer 
discards any characters that exceed the specified 
right margin. 

The width of the specified form. 


TRUE or FALSE to indicate whether the printer 
prints any characters that exceed the specified 
right margin on the following line. 


The names of the execution queues that are 
enabled to accept work from the specified 
generic queue. This item code is meaningful 
only for generic queues. 


The number of jobs in the queue being held until 
explicitly released. 


The number of blocks associated with pending 
jobs in the queue that were skipped during 
the current call to FSGETQUI. These jobs 
were not reported because they did not match 
the selection criterion in effect for the call to 
F$GETQUI. 

The number of of pending jobs in the queue 
that were skipped during the current call to 
F$GETQUI. These jobs were not reported 
because they did not match the selection 
criterion in effect for the call to FSGETQUI. 
TRUE or FALSE to indicate whether the system 
is attempting to abort the execution of a job. 


~ The name of the queue on which the specified 


job executed. 

The time at which the execution of the specified 
job completed. 

The number of times the specified print job is to 
be repeated. 

The number of times that the specified print job 
has been repeated. 

TRUE or FALSE to indicate whether a CPU 
time limit is specified for the job. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) F$GETQUI Items 


Return 
Item | Type 
JOB_ERROR_RETENTION! String 
JOB_EXECUTING String 
JOB_FILE BURST! — String 
JOB_FILE_BURST_ONE}! String 
JOB_FILE_FLAG! String 
JOB_FILE_ FLAG ONE! | String 
JOB_FILE_PAGINATE! String 
JOB_FILE_TRAILER! String 
JOB FILE TRAILER ONE! String 


Lexical Functions 
FSGETQUI 


Information Returned 


TRUE or FALSE to indicate whether the user 
requested that the specified job be retained in 
the queue if the job completes unsuccessfully. 
TRUE or FALSE to indicate whether the 
specified job is executing or printing. 

TRUE or FALSE to indicate whether a burst 
page option is explicitly specified for the job. 
TRUE or FALSE to indicate whether burst and 
flag pages precede only the first copy of the first 
file in the job. 

TRUE or FALSE to indicate whether a flag page 
precedes each file in the job. 

TRUE or FALSE to indicate whether a flag page 
precedes only the first copy of the first file in the 
job. 

TRUE or FALSE to indicate whether a paginate 
option is explicitly specified for the job. 

TRUE or FALSE to indicate whether a trailer 
page follows each file in the job. 

TRUE or FALSE to indicate whether a trailer 
page follows only the last copy of the last file in 
the job. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Return 
Item Type - 
JOB FLAGS! Integer 
JOB_HOLDING String 
JOB_INACCESSIBLE String 
JOB_LIMIT Integer 


Information Returned 


The processing options selected for the specified 
job. The integer represents a bit field. To find 
the settings of each bit in the field, use one of 
the following items in place of JOB_FLAGS: 


JOB_CPU_LIMIT 
JOB_ERROR_RETENTION 
JOB_FILE_BURST 
JOB_FILE_BURST_ONE 
JOB_FILE_FLAG 
JOB_FILE_FLAG_ONE 
JOB_FILE_PAGINATE 
JOB_FILE_TRAILER 
JOB_FILE_TRAILER_ONE 
JOB_LOG_DELETE 
JOB_LOG_NULL 
JOB_LOG_NULL 
JOB_LOG_SPOOL 
JOB_LOWERCASE 
JOB_NOTIFY 
JOB_RESTART 
JOB_RETENTION_TIME 
JOB_WSDEFAULT 
JOB_WSEXTENT 
JOB_WSQUOTA 


TRUE or FALSE to indicate whether the job will 
be held until it is explicitly released. | 


TRUE or FALSE to indicate whether the caller 
does not have read access to the specific job and 
file information in the system queue file. When 
FALSE, the DISPLAY_JOB and DISPLAY_FILE 
operations can return information for only the 
following output value item codes: 


AFTER_TIME 
COMPLETED_BLOCKS 
ENTRY_NUMBER 
INTERVENING_BLOCKS 
INTERVENING_JOBS 
JOB_SIZE 

JOB_STATUS 


- The number of jobs that can execute 


simultaneously on the specified queue. This 
item code is applicable only to batch execution 
queues. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-—11 (Cont.) FSGETQUI Items 


Item 
JOB_LOG_DELETE! 


JOB_LOG_NULL! 


JOB_LOG_SPOOL! 
JOB_LOWERCASE! 


JOB_NAME! 
JOB_NOTIFY! 


JOB_PENDING 
JOB_PID 


JOB_REFUSED 


JOB_RESET_MODULES 


JOB_RESTART! 


JOB_RETAINED 


JOB_RETENTION 


JOB_RETENTION_TIME! 


JOB_SIZE 


Return 
Type 


String 
String 


String 


String 


String 
String 


String 
String 


String 


String 


String 


String 


String 


String 


Integer 


Lexical Functions 
FSGETQUI 


Information Returned 


TRUE or FALSE to indicate whether the log file 
is deleted after it is printed. 

TRUE or FALSE to indicate whether a log file is 
not created. 

TRUE or FALSE to indicate whether the job 
log file is queued for printing when the job is 
complete. 

TRUE or FALSE to indicate whether the job is 
to be printed on a printer that can print both 
uppercase and lowercase letters. 

The name of the specified job. 

TRUE or FALSE to indicate whether a message 
is broadcast to a terminal when a job completes 
or aborts. 

TRUE or FALSE to indicate whether the job is 
pending. 


- The process identification (PID) number of the 


executing batch job. 


TRUE or FALSE to indicate whether the job was 
refused by the symbiont and is waiting for the 
symbiont to accept it for processing. 


The names of the text modules that are to be 
extracted from the device control library and 
copied to the printer before each job in the 
specified queue is printed. This item code is 
meaningful only for output execution queues. 


TRUE or FALSE to indicate whether the job will 
restart after a system failure or can be requeued 
during execution. 


TRUE or FALSE to indicate whether the job has 
completed but is being retained in the queue. 


TRUE or FALSE to indicate whether the user 
requested that the job be retained indefinitely 
in the queue regardless of the job’s completion 
status. 


Returns the system time until which the user 
requested the job be retained in the queue. The 
system time may be expressed in either absolute 
or delta time format. 


The total number of blocks in the specified print 
job. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) F$GETQUI Items 


Return 
Item Type 
JOB. SIZE_MAXIMUM Integer 
JOB_SIZE_MINIMUM Integer 
JOB_STALLED String 
JOB_STARTING String © 
JOB_STATUS Integer 
JOB_SUSPENDED String 
JOB_TIMED_RELEASE String 
JOB_WSDEFAULT! String 
JOB_WSEXTENT! String 
JOB_WSQUOTA! String 


Information Returned 


The maximum number of blocks that a print job 
initiated from the specified queue can contain. 
This item code is applicable only to output 
execution queues. — 


The minimum number of blocks that a print job 
initiated from the specified queue can contain. 
This item code is applicable only to output 
execution queues. 

TRUE or FALSE to indicate whether the 
specified job is stalled because the physical 
device on which the job is printing is stalled. 
TRUE or FALSE to indicate whether the-job_ 
controller is starting to process the job and has 


- begun communicating with an output symbiont 


or a job controller on another node. 


The specified job’s status flags. The integer 
represents a bit field. To find the settings of 
each bit in the field, use one of the following 
items in place of JOB_STATUS: 


JOB_ABORTING 
JOB_EXECUTING 
JOB_HOLDING 
JOB_INACCESSIBLE — 
JOB_PENDING 
JOB_REFUSED 
JOB_RETAINED 
JOB_STALLED 
JOB_STARTING 
JOB_SUSPENDED 
JOB_TIMED_RELEASE 


- TRUE or FALSE to indicate whether the job is 


suspended. 


TRUE or FALSE to indicate whether the job is 
waiting for a specified time to execute. 


TRUE or FALSE to indicate whether a default 
working set size is specified for the job. 


TRUE or FALSE to indicate whether a working 
set extent is specified for the job. 


TRUE or FALSE to indicate whether a working 
set quota is specified for the job. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 


DCLi-360 


(continued on next page) 


Table DCLI-11 (Cont.) FSGETQUI Items 


Item 
LAST PAGE! 


LIBRARY_SPECIFICATION 


LOG_QUEUE! 
LOG_SPECIFICATION! 


MANAGER_NAME 
MANAGER_NODES 


MANAGER_STATUS 


NOTE} 


OPERATOR_REQUEST! 


OWNER_UIC! 


PAGE_SETUP_MODULES 


Return 
Type 


Integer 


String 


String 


String 


String 
String 


Integer 


String 


String 


String 


String 


Lexical Functions 
FSGETQUI 


Information Returned 


The page number at which the printing of the 
specified file should end. This item code is 
applicable only to output execution queues. 


The name of the device control library for 

the specified queue. The library specification 
assumes the device and directory name 
SYS$LIBRARY and a file type of TLB. This item 
code is meaningful only for output execution 
queues. 


The name of the queue into which the log 

file produced for the specified batch job is to be 
entered for printing. This item code is applicable 
only to batch jobs. 


The name of the log file specified for a job. This 
item code is meaningful only for batch jobs. Use 
the JOB_LOG_NULL item code to determine 
whether a log file will be produced. 


The queue manager name. 


The names of the nodes on which the queue 
manager may run. 


The specified queue manager’s status flags. To 
find the settings of each bit in the field, use one 
of the following items in place of JOB_STATUS: 


MANAGER_FAILOVER 
MANAGER_RUNNING 
MANAGER_START_PENDING 
MANAGER_STARTING 
MANAGER_STOPPED 
MANAGER_STOPPING 


The note that is to be printed on the job flag and 
file flag pages of the specified job. This item code 
is meaningful only for output execution queues. 


The message that is to be sent to the queue 
operator before the specified job begins to 
execute. This item code is meaningful only 

for output execution queues. 

The owner user identification code (UIC) of the 
specified queue. 

The names of the text modules to be extracted 
from the device control library and copied to the 
printer before each page of the specified form is 
printed. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) F$GETQUI Items 


ltem 


PARAMETER. 1 to 
PARAMETER, 81 


PENDING_JOB_BLOCK_ 
COUNT 


PENDING_JOB_COUNT 


PENDING_JOB_REASON 


PEND_CHAR_MISMATCH 
PEND_JOB_SIZE_MAX 
PEND_JOB_SIZE_MIN 


PEND_LOWERCASE_ 
MISMATCH 


PEND_NO_ACCESS 


PEND_QUEUE_BUSY 


PEND_QUEUE_STATE 


Return 
Type 


String 
Integer 


Integer 


Integer 


String 
String 
String 


String 


String 


String 


String 


Information Returned 


The value of the user-defined parameters that 
become the value of the DCL symbols P1 to P8 
respectively. 


The total number of blocks for all pending jobs 
in the queue (valid only for output execution 
queues). 


The number of jobs in the queue in a pending 
state. 


The reason that the job is in a pending state. 
The integer represents a bit field. To find the 
settings of each bit in the field, use one of the 
following items in place of PENDING_JOB_ 
REASON: 


PEND_CHAR_MISMATCH 
PEND_JOB_SIZE_MAX 
PEND_JOB_SIZE_MIN 
PEND_LOWERCASE_MISMATCH 
PEND_NO_ACCESS 
PEND_QUEUE_BUSY 
PEND_QUEUE_STATE 
PEND_STOCK_MISMATCH 


TRUE or FALSE to indicate whether the job 
requires characteristics that are not available on 
the execution queue. | 

TRUE or FALSE to indicate whether the block 
size of the job exceeds the upper block limit of 
the execution queue. 

TRUE or FALSE to indicate whether the block 
size of the job is less than the lower limit of the 
execution queue. 


TRUE or FALSE to indicate whether the job 
requires a lowercase printer. 


TRUE or FALSE to indicate whether the owner 
of the job does not have access to the execution 
queue. 


TRUE or FALSE to indicate whether the job is 
pending because the number of jobs currently 
executing on the queue equals the job limit for 
the queue. 

TRUE or FALSE to indicate whether the job is 
pending because the execution queue is not ina 
running open state. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 


PEND_STOCK_MISMATCH 


PRIORITY! 
PROCESSOR 


PROTECTION! 
QUEUE_ACL_SPECIFIED 


QUEUE_ALIGNING 


QUEUE_AUTOSTART 


QUEUE_AUTOSTART_ 
INACTIVE 


QUEUE_AVAILABLE 


QUEUE_BATCH 


QUEUE_BUSY 
QUEUE_CLOSED 
QUEUE_CPU_DEFAULT 
QUEUE_CPU_LIMIT 


QUEUE_DESCRIPTION 


Return 
Type 


String 


Integer 
String 


String 
String 


String 


String 


String 


String 


String 


String 
String 
String 
String 


String 


Lexical Functions 
| FSGETQUI 


Information Returned 


TRUE or FALSE to indicate whether the stock 
type required by the job’s form does not match 
the stock type of the form mounted on the 
execution queue. 


The scheduling priority of the specified job. 


The name of the symbiont image that executes 
print jobs initiated from the specified queue. 


The specified queue’s protection mask. 


TRUE or FALSE to indicate whether an access 
control list has been specified for the queue. 


TRUE or FALSE to indicate whether the queue 
is currently printing alignment pages. A queue 
prints alignment pages when it is restarted from 
a paused state by using the command START 
/QUEUE/ALIGN. 

TRUE or FALSE if the specified queue has been 
designated as an AUTOSTART queue. 

TRUE or FALSE if the queue is an autostart 
queue that will not be automatically started. 

If TRUE, a START/QUEUE or INIT/QUEUE 
/START command must be issued to restart the 
queue. 

TRUE or FALSE if the queue is processing one 
or more jobs but is capable of processing one or 
more additional jobs. 

TRUE or FALSE to indicate whether the queue 
is a batch queue or a generic batch queue. 


TRUE or FALSE if the number of jobs currently 
executing on the queue equals the job limit for 
the queue. 

TRUE or FALSE to indicate whether the queue 
is closed and will not accept new jobs until the 
queue is put in an open state. 


TRUE or FALSE to indicate whether a default 
CPU time limit has been specified for all jobs in 
the queue. 


TRUE or FALSE to indicate whether a 
maximum CPU time limit has been specified 
for all jobs in the queue. 

The description of the queue that was defined 


by using the (DESCRIPTION qualifier with the 
INITIALIZE/QUEUE command. 


lRequires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 


(continued on next page) 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 


QUEUE_DIRECTORY 


QUEUE_FILE_BURST 
QUEUE_FILE_BURST_ONE 
QUEUE_FILE_FLAG 
QUEUE_FILE_FLAG_ONE 


QUEUE_FILE_PAGINATE 


QUEUVE_FILE_TRAILER 


QUEUE_FILE_TRAILER_ONE 
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Return 
Type 


String 


String 
String 
String 
String 


String 


String 


String 


Information Returned 


The device and directory specification of the 
queue database directory for the queue manager. 


TRUE or FALSE to indicate whether burst and 

flag pages precede each file in each job initiated 
from the queue. 

TRUE or FALSE to indicate whether burst and 

flag pages precede only the first copy of the first 
file in each job initiated from the queue. 

TRUE or FALSE to indicate whether a flag page 
precedes each file in each job initiated from the 

queue. 


TRUE or FALSE to indicate whether a flag page 
precedes only the first copy of the first file in 
each job initiated from the queue. 


TRUE or FALSE to indicate whether the output 
symbiont paginates output for each job initiated 
from this queue. The output symbiont paginates 
output by inserting a form feed whenever output 
reaches the bottom margin of the form. 

TRUE or FALSE to indicate whether a trailer 
page follows each file in each job initiated from 
the queue. 

TRUE or FALSE to indicate whether a trailer 
page follows only the last copy of the last file in 
each job initiated from the queue. 


(continued on next page) 


Table DCLI-11 (Cont.) FSGETQUI Items 


Return 


Item Type 
QUEUE_FLAGS Integer 
QUEUE_GENERIC String 
QUEUE_GENERIC_ String 
SELECTION 

QUEUE_IDLE String 


Lexical Functions 
FSGETQUI 


Information Returned 


The processing options that have been selected 
for the specified queue. The integer represents 
a bit field. To find the settings of each bit in the 
field, use one of the following items in place of 
QUEUE_FLAGS: 


QUEUE_ACL_SPECIFIED 
QUEUE_AUTOSTART 
QUEUE_BATCH 
QUEUE_CPU_DEFAULT 
QUEUE_CPU_LIMIT 
QUEUVE_FILE_BURST 
QUEUE_FILE_BURST_ONE 
QUEUE_FILE_FLAG 
QUEUE_FILE_FLAG_ONE 
QUEUE_FILE_PAGINATE 
QUEUE_FILE_TRAILER 
QUEUE_FILE_TRAILER_ONE 
QUEUE_GENERIC 
QUEUE_GENERIC_SELECTION 
QUEUE_JOB_BURST 
QUEUE_JOB_FLAG 
QUEUE_JOB_SIZE_SCHED 
QUEUE_JOB_TRAILER 
QUEUE_PRINTER 
QUEUE_RECORD_BLOCKING 
QUEUE_RETAIN_ALL 


QUEUE_RETAIN_ERROR 
QUEUE_SWAP 
QUEUE_TERMINAL 
QUEUE_WSDEFAULT 
QUEUE_WSEXTENT 
QUEUE_WSQUOTA 


TRUE or FALSE to indicate whether the queue 
is a generic queue. 

TRUE or FALSE to indicate whether the queue 
is an execution queue that can accept work from 
a generic queue. 

TRUE or FALSE to indicate whether the queue 
is not processing any jobs and is capable of 
doing so or whether the generic queue is capable 
of feeding executor queues. - 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 
QUEUE_JOB_BURST 


QUEUE_JOB_FLAG 


QUEUE_JOB_SIZE_SCHED 


QUEUE_JOB_TRAILER 


QUEUE_LOWERCASE 


QUEUE_NAME! 


QUEUE_PAUSED 
QUEUE_PAUSING 
QUEUE_PRINTER 
QUEUE_RECORD_BLOCKING 


QUEUE_REMOTE 


QUEUE_RESETTING 
QUEUE_RESUMING 


QUEUE_RETAIN_ALL 


Return 
Type 


String 


String 


String 


String 


String 


String 


String 


String 


String 


String 


String 


String 
String 


String 


Information Returned 


TRUE or FALSE to indicate whether burst and 
flag pages precede each job initiated from the 
queue. 


TRUE or FALSE to indicate whether a flag page 
precedes each job initiated from the queue. 


TRUE or FALSE to indicate whether jobs 
initiated from the queue are scheduled according 
to size with the smallest job of a given priority 
processed first. (Meaningful only for output 
queues.) 


TRUE or FALSE to indicate whether a trailer 
page follows each job initiated from the queue. 


TRUE or FALSE to indicate whether queue is 
associated with a printer that can print both 
uppercase and lowercase characters. 


The name of the specified queue or the name of 
the queue that contains the specified job. 
TRUE or FALSE to indicate whether execution 
of all current jobs in the queue is temporarily 
halted. 

TRUE or FALSE to indicate whether the queue 
is temporarily halting execution. Currently 
executing jobs are completing; temporarily, no 
new jobs can begin executing. 

TRUE or FALSE to indicate whether the queue 
is a printer queue. 

TRUE or FALSE to indicate whether the 
symbiont is permitted to concatenate, or block 
together, the output records it sends to the 
output device. 

TRUE or FALSE to indicate whether the queue 
is assigned to a physical device that is not 
connected to the local node. 

TRUE or FALSE to indicate whether the queue 
is resetting and stopping. 

TRUE or FALSE to indicate whether the queue 
is restarting after pausing. 

TRUE or FALSE to indicate whether all jobs 
initiated from the queue remain in the queue 
after they finish executing. Completed jobs are: 
marked with a completion status. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Return 


Item Type 
QUEUE_RETAIN_ERROR String 
QUEUE_SERVER String 
QUEUE_STALLED String 
QUEUE_STARTING String 
QUEUE_STATUS Integer 
QUEUE_STOP_PENDING String 
QUEUE_STOPPED String 
QUEUE_STOPPING String 


Lexical Functions 
FSGETQUI 


Information Returned 


TRUE or FALSE to indicate whether only jobs 
that do not complete successfully are retained in 
the queue. 


TRUE or FALSE to indicate whether queue 
processing is directed to a server symbiont. 


TRUE or FALSE to indicate whether the 
physical device to which the queue is assigned is 
stalled; that is, the device has not completed the 
last I/O request submitted to it. 


TRUE or FALSE to indicate whether the queue 
is starting. 

The specified queue’s status flags. The integer 
represents a bit field. To find the settings of 


each bit in the field, use one of the following 
items in place of QUEUE_STATUS: 


QUEUE_ALIGNING 
QUEUE_AUTOSTART 
QUEUE_AUTOSTART INACTIVE 
QUEUE_AVAILABLE 
QUEUE_BUSY 
QUEUE_CLOSED 
QUEUE_IDLE 
QUEUE_LOWERCASE 
QUEUE_PAUSED 
QUEUE_PAUSING 
QUEUE_REMOTE 


QUEUE_RESETTING 
QUEUE_RESUMING 
QUEUE_SERVER 
QUEUE_STALLED 
QUEUE_STARTING 
QUEUE_STOP_PENDING 
QUEUE_STOPPED 
QUEUE_STOPPING 
QUEUE_UNAVAILABLE 


TRUE or FALSE if queue will be stopped when 
jobs currently in progress have completed. 


TRUE or FALSE to indicate whether the queue 
is stopped. . 


TRUE or FALSE to indicate whether the queue 
is stopping. 
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Table DCLI-11 (Cont.) FSGETQUI Items 


Item 
QUEUE_SWAP 


QUEUE_TERMINAL 


QUEUE_UNAVAILABLE 


QUEUVUE_WSDEFAULT 


QUEUE_WSEXTENT 


QUEUE_WSQUOTA 


REQUEUE_QUEUE_NAME! 
RESTART_QUEUE_NAME! 


RETAINED_JOB_COUNT 


SECURITY_INACCESSIBLE 


SCSNODE_NAME — 


SUBMISSION_TIME! 


TIMED_RELEASE_JOB_ 
COUNT 


UIC! 


USERNAME! 
WSDEFAULT! 


Return 
Type 

String 
String 


String 


String 


String 


String 


String 
String 


Integer 


String 


String 


String 
Integer 
String 


String 
Integer 


Information Returned 


TRUE or FALSE to indicate whether jobs 
initiated from the queue can be swapped. 


TRUE or FALSE to indicate whether the queue 
is a terminal queue. 


TRUE or FALSE to indicate whether the 
physical device to which queue is assigned is 
not available. 


TRUE or FALSE to indicate whether a default 
working set size is specified for each job initiated 
from the queue. 


TRUE or FALSE to indicate whether a working 
set extent is specified for each job initiated from 
the queue. 


TRUE or FALSE to indicate whether a working 
set quota is specified for each job initiated from 
the queue. 


The name of the queue to which the specified job 
is reassigned. 


The name of the queue in which the job will be 
placed if the job is restarted. 


The number of jobs in the queue retained after 
successful completion plus those retained on 
error. 


TRUE or FALSE to indicate whether the user 
has read access to the specified queue. 


The 6-byte name of the VAX node on which jobs 
initiated from the specified queue execute. The 
node name matches the value of the system 
parameter SCSNODE for the target node. 


The time at which the specified job was 
submitted to the queue. 

The number of jobs in the queue on hold until a 
specified time. 


The user identification code (UIC) of the owner 
of the specified job. 

The user name of the owner of the specified job. 
The default working set size specified for the 
specified job or queue. This value is meaningful 
only for batch jobs and execution and output 
queues. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 
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FSGETQUI 
Table DCLI-11 (Cont.) FSGETQUI Items 
Return 
ltem Type Information Returned 
WSEXTENT! Integer The working set extent specified for the specified 
job or queue. This value is meaningful only for 
batch jobs and execution and output queues. 
WSQUOTA! Integer The working set quota for the specified job or 


queue. This value is meaningful only for batch 
jobs and execution and output queues. 


1Requires Read (R) access if used with one of the function codes: DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE. 


Examples 


1. 


2. 


$ 


3 


BLOCKS = FSGETQUI("DISPLAY ENTRY" ,"JOB SIZE", 1347) 


In this example, the FSGETQUI lexical function is used to obtain the size in 
blocks of print job 13847. The value returned reflects the total number of blocks 
occupied by the files associated with the job. 


IF F$GETQUI("DISPLAY QUEUE", "QUEUE STOPPED", "VAX1_ BATCH") .EQS. 


"TRUE" THEN GOTO 500 


In this example, the FSGETQUI lexical function is used to return a value of 
TRUE or FALSE depending on whether the queue VAX1_BATCH is in a stopped 
state. If VAX1_BATCH is not in the system, FSGETQUI returns a null string 

( met ). 


This command procedure shows all queues and the jobs in them. 
TEMP = FSGETQUI("") 


QLOOP: 
QNAME = FSGETQUI("DISPLAY QUEUE", "QUEUE NAME","*") 
IF QNAME .EQS. "" THEN EXIT 


WRITE SYSSOUTPUT "" 

WRITE SYSSOUTPUT "QUEUE: ", QNAME 

JLOOP: 

NOACCESS = FSGETQUI("DISPLAY JOB","JOB INACCESSIBLE", ,"ALL JOBS") 
IF NOACCESS .EQS. "TRUE" THEN GOTO JLOOP 

IF NOACCESS .EQS. "" THEN GOTO QLOOP 

JNAME = FSGETQUI("DISPLAY JOB","JOB NAME", ,- 

"FREEZE CONTEXT,ALL JOBS") 


WRITE SYSSOUTPUT " JOB: ", JNAME 
GOTO JLOOP 


This sample command procedure displays all the queues in the system.and all the 
jobs to which the user has read access in the system. In the outer loop a wildcard 
display queue operation is performed. No call is made to establish the right to 
obtain information about the queue, because all users have implicit read access 
to queue attributes. Because a wildcard queue name is specified (“*”), wildcard 
queue context is maintained across calls to FSGETQUI. 


In the inner loop, to obtain information about all jobs, we enter nested wildcard 
mode from wildcard display queue mode. In this loop, a call is made to establish 
the right to obtain information about these jobs because users do not have 
implicit read access to jobs. The FREEZE_CONTEXT keyword is used in the 
request for a job name to prevent the advance of the wildcard context to the next 
object. After the job name has been retrieved and displayed, the procedure loops 
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FSGETQUI 
back up for the next job. The context is advanced because the procedure has not 
used the FREEZE_CONTEXT keyword. The wildcard queue context is dissolved 
when the list of matching queues is exhausted. Finally, FSGETQUI returns a 
null string ("") to denote that no more objects match the specified search criteria. 
4. $ THIS NODE = PSEDIT(FSGETSYI("SCSNODE") , "COLLAPSE" ) 


$ TEMP = FSGETQUI("CANCEL OPERATION") 

$ SET NOON 

SLOOP: 

$ QUEUE = FS$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*", "WILDCARD" ) 

$ IF QUEUE .EQS. "" THEN GOTO ENDLOOP 

$ IF THIS NODE .EQS.- 

FSGETQUI("DISPLAY QUEUE","SCSNODE NAME","*", "WILDCARD, FREEZE CONTEXT") 

$ THEN - ~ - 

$ IF .NOT.- 
FSGETQUI ("DISPLAY QUEUE", "QUEUE_AUTOSTART","*", "WILDCARD, FREEZE CONTEXT" )- 
THEN START/QUEUE ‘QUEUE’ 

$ ENDIF 

$ GOTO LOOP 

SENDLOOP: 

$ SET ON 


This command procedure looks at all queues associated with the local cluster 
node and starts any queue that is not marked as autostart. 


The procedure starts by obtaining the nodename of the local system and clearing 
the F$GETQUI context. In addition, error handling is turned off for the loop so 
that, if a queue had been started previously, the resulting error from ie START 
QUEUE command does not abort the command procedure. 


Inside the loop, the FSGETQUI function gets the next queue name in the queue 
list. If the result is empty, then it has reached the end of the list and it exits the 
loop. 


The next IF statement checks to see if the queue runs on the local node. If it 
does, then the next statement checks to see if the queue is marked as an autostart 
queue. If that is false, then the queue is started with the start command. The 
loop is then repeated. 


The final command of the procedure restores DCL error handling to the previous 
setting. 
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Format 


Lexical Functions 
FSGETSYI 


Returns status and identification information about the local system (or about a 
node in the local dual-architecture VMScluster system, if your system is part of a 
VMScluster). 


FSGETSYI(item [,node-name] [,cluster-id]) 


Return Value 


Arguments 


Either an integer or a character string, depending on the item you request. 


item 

Indicates the type of information to be reported about the local node (or about 
another node in your VMScluster, if your system is part of a VMScluster). Specify 
the item as a character string expression. 


You can specify the items in Table DCLI—12 only for your local node; you cannot 
specify the node argument with these items. You can specify these items whether 
or not you are in a VMScluster or VAXcluster system. 


You can specify the items in Table DCLI-13 for either your local node or for 
another node in your VAXcluster. The information in this table is returned for 
your local node if you do not specify the node-name argument; the information 
is returned for the specified node if you include the node-name argument. Your 
system must be a member of a VMScluster or VAXcluster system in order to 
specify the items in this table, except for CLUSTER_MEMBRER. You can specify 
CLUSTER_MEMBER whether or not your system is a member of a VMScluster 
or VAXcluster system. 


You can also specify any of the system parameters listed in the OpenVMS 
System Management Utilities Reference Manual. However, you can specify system 
parameters only for your local node; you cannot specify the node-name argument 
with these items. 


node-name 

Specifies the node in your VMScluster or VAXcluster system for which 
information is to be returned. Specify the node as a character string expression. 
You cannot use the asterisk (*) and the percent sign (%) wildcard characters to 
specify the node-name argument. (This argument can be specified only if your 
system is part of a VMScluster or VAXcluster.) 


You can request information about another node in your VMScluster or 
VAXcluster system only when you specify an item from Table DCLI-13. If 
you do not specify a node, the default is the current node. 


cluster-id 

Specifies the cluster node identification number for which the information is to 
be returned. (This argument can be specified only if your system is part of a 
VMScluster or VAXcluster.) 


You can request information about another node in your VMScluster or 
VAXcluster system only when you specify an item from Table DCLI-138. If 
you do not specify a node, the default is the current node. 
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Description 
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To get information for all the nodes in a cluster, use the F$CSID lexical function 
to obtain each cluster system identification number and use the cluster-id 
argument of F$GETSYI to gather information about each node. 


The F$GETSYI lexical function invokes the $GETSYI system service to return 
status and identification information about the local system (or about a node 
in the local VMScluster or VAXcluster, if your system is part of a cluster). The 
F$GETSYI function returns information on the items that can be specified with 
the $GETSYI system service. For more information on the $GETSYI system 
service, see the OpenVMS System Services Reference Manual. 


You can specify the node for which you want information by supplying either the 
node-name or the cluster-id argument, but not both. 


Table DCLI-—12 lists the items you can specify with the FSGETSYI lexical function 
to get information about your local node. Table DCLI-13 lists the items you can 
specify to get information about either your local node or another node in your 
VMScluster or VAXcluster system. 


Table DCLI-12 FSGETSYI Items for the Local Node Only 


Return 

Item Type | Information Returned 

ACTIVECPU_CNT Integer The count of CPUs actively 
participating in the current boot of 
a symmetric multiprocessing (SMP) 
system. 

ARCHFLAG . String Architecture flags for the system. 

ARCH_NAME String Name of CPU architecture; Alpha for 
OpenVMS Alpha, VAX for OpenVMS 
VAX. 

ARCH_TYPE Integer Type of CPU architecture; 1 for VAX, 2 
for Alpha. 

AVAILCPU_CNT Integer The count of CPUs recognized in the 
‘system. 

BOOTTIME String The time the system was booted. 

CHARACTER _ String TRUE or FALSE to indicate whether 

EMULATED the character string instructions are 
emulated on the CPU. 

~£CONSOLE_VERSION String Console firmware version. 

CONTIG_GBLPAGES Integer Total number of free, contiguous global 
pages. 


Alpha specific. 
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Table DCLI-12 (Cont.) FSGETSYI Items for the Local Node Only 


Item 


+CPU 


tCPUTYPE 


DECIMAL_EMULATED 
D_FLOAT_EMULATED 
ERRORLOGBUFFERS 
F_FLOAT_EMULATED 


FREE_GBLPAGES 
FREE_GBLSECTS 


G_FLOAT_EMULATED 


+GH_RSRVPGCNT 


tITB_ENTRIES 


MEMSIZE 


PAGEFILE_FREE 


+VAX specific. 
Alpha specific. 


Return 
Type 


Integer 


Integer 


String 


' String 


Integer 


String 


Integer 
Integer 


String 


Integer 


Integer 


Integer 


Integer 


Information Returned 


On VAX, the processor type, as 
represented in the processor’s system 
identification (SID) register. For 


- example, the integer 1 represents 


a VAX-11/780 and the integer 6 
represents a VAX 8530, VAX 8550, 
VAX 8700, or VAX 8800. 


On Alpha, the processor type, as stored 
in the hardware restart parameter 
block (HWRPB). The value of 2 
represents a DECchip 21064 processor. 


TRUE or FALSE to indicate whether 
the decimal string instructions are 
emulated on the CPU. 


TRUE or FALSE to indicate whether 
the D_floating instructions are 
emulated on the CPU. 


Number of system pages (on VAX) 
or pagelets (on Alpha) to be used as 
errorlog buffers. 

TRUE or FALSE to indicate whether 
the F_floating instructions are 
emulated on the CPU. 

Current count of free global pages. 


Current count of free global section 
table entries. 


TRUE or FALSE to indicate whether 
the G_floating instructions are 
emulated on the CPU. 

On Alpha, number of pages covered 
by granularity hints to reserve for use 
by the INSTALL utility after system 
startup has completed. — 

On Alpha, number of I-stream — 
translation buffer entries which 
support granularity hints to be 
allocated for resident code. 

Number of pages of memory in the 
system configuration. 

Number of free pages in the currently 
installed paging files. 
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Table DCLI-12 (Cont.) FSGETSYI Items for the Local Node Only 


Item 
PAGEFILE_PAGE 


+PALCODE_VERSION 
QUANTUM 


SID 


SWAPFILE_FREE 
SWAPFILE_PAGE 


SYSTEM_RIGHTS 


tSYSTYPE 


USED_GBLPAGCNT 
USED_GBLPAGMAX 


VERSION 


tAlpha specific. 
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Return 
Type 
Integer 


String 
Integer 


Integer 


Integer 
Integer 


String 


Integer 


Integer 
Integer 


String 


Information Returned 


Number of pages in the currently 
installed paging files. 


Version of the PALCODE (privileged 
architectural library) on your Alpha 
system. 


Maximum amount of processor time 
a process can receive while other 
processes are waiting. 


System identification register. On 
Alpha, returns a value where all fields 
are zero except the CPU type field, 
which always contains the value of 
256. 


Number of free pages in the currently 
installed swapping files. 


Number of pages in the currently 
installed swapping files. 


The contents of the system rights list 
on the local system. If you specify a 
remote system, a null string (""") is 
returned. This item code returns a 
list of identifier names separated by 
commas (, ). 


On Alpha, the family or system 
hardware platform. For example, 
the integer 2 represents a DEC 4000, 
the integer 3 represents a DEC 7000 
or DEC 10000, and the integer 4 
represents a DEC 3000. 

Number of pages currently in use in 
the global page table. 

Maximum number of pages ever in use 
in the global page table. 

Version of OpenVMS in use (8- 


character string filled with trailing 
blanks). 
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Table DCLI-13 FS$GETSYI Items for the Local Node or for Other Nodes in the 


VAXcluster 

Return 
Item Type 
CLUSTER_EVOTES Integer 
CLUSTER_FSYSID String 
CLUSTER_FTIME String 
CLUSTER_ String 
MEMBER 
CLUSTER_NODES Integer 
CLUSTER_ Integer 
QUORUM 
CLUSTER_VOTES Integer 
DECNET_ String 
FULLNAME 
HW_MODEL Integer 
HW_NAME String 
NODENAME String 
NODE_AREA Integer 
NODE_CSID String 
NODE_EVOTES Integer 
NODE_HWTYPE String 
NODE_HWVERS String 
NODE_NUMBER Integer 
NODE_QUORUM Integer 
NODE_SWINCARN _ String 


Information Returned 


Total number of votes in the cluster. 


System identification number for first node to 
boot in the cluster (the founding node). This 
number is returned as a character string 
containing a hexadecimal number. 

The time when the first node in the cluster 
was booted. 

TRUE or FALSE if the node is a member of 
the local cluster. 

Total number of nodes in the cluster, as an 
integer. 

Total quorum for the cluster. 


Total number of votes in the cluster. 

The node name of a DECnet Phase IV system 
or the node full name of a DECnet/OSI 
system. 

An integer that identifies the node’s Alpha 
or VAX model type. An integer greater than 
1023 represents the Alpha operating system 
and an integer less than or equal to 1023 
represents the VAX operating system. 

The Alpha or VAX model name. 

Node name (does not include the following 
double colon). 

The DECnet area for the target node. 

The CSID of the specified node, as a string 
containing a hexadecimal number. The CSID 
is a form of system identification. 

Number of votes allotted to the node. 
Hardware type of the specified node. 
Hardware version of the specified node. 

The DECnet number for the specified node. 
Quorum that the node has. . 
Software incarnation number for the 


specified node. This number is returned as a 
string containing a hexadecimal number. 
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Item 


NODE_SWTYPE 
NODE_SWVERS 
NODE_SYSTEMID 
NODE_VOTES 


+ REAL_CPUTYPE 


SCS_EXISTS 


VECTOR_ 
EMULATOR 


VP_MASK 


VP_NUMBER 


_ Table DCLI-13 (Cont.) FSGETSY! Items for the Local Node or for Other Nodes 


in the VAXcluster 


Return 
Type 


String 


String 
String 


Integer 


_ String 


String 
Boolean 


Integer 


Integer 


1. $ SYSID = FSGETSYI("SID") 
$ SHOW SYMBOL SYSID 
SYSID = 19923201 Hex = 01300101 Octal = 000401 


This example shows how to use the F$GETSYI function to return the 
information in the system identification register. Use quotation marks (“”) 
around the argument SID because it is a string literal. The value returned by 
F$GETSYI is assigned to the symbol SYSID. Because a node is not specified, 
information about your current node is returned. 


information Returned 


Type of operating system software used by 
the specified node. 


Software version of the specified node. 


- System identification number for the 


specified node. This number is returned as.a 
string containing a hexadecimal number. 
Number of votes allotted to the node. 

The actual CPU type of the primary CPU of 
the system. 


TRUE or FALSE to indicate whether the 
system communication subsystem (SCS) is 
currently loaded on a VAX node. 

Flag indicating the presence of the VAX 
vector instruction emulator facility (VVIEF) 
in the system. 

Mask indicating which processors in the 
system have vector coprocessors. 


Number of vector processors in the system. 


2. $ MEM = FSGETSYI("CLUSTER MEMBER", "LONDON") 


$ SHOW SYMBOL MEM 


MEM = "TRUE" 


This example uses the F$GETSYI function to determine whether the node 
LONDON is a member of the local cluster. The return value TRUE indicates 
that the remote node LONDON is a member of the cluster. 


8. $ LIM = FSGETSYI("BJOBLIM") 


$ SHOW SYMBOL LIM 
Hex = 00000010 Octal = 00000000020 


LIM = 16 


This example uses the system parameter BJ OBLIM as an argument for 
the F$GETSYI function. This argument returns the batch job limit for the 


current system. 
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FSIDENTIFIER 


Format 


Converts an alphanumeric identifier to its integer equivalent, or converts an 
integer identifier to its alphanumeric equivalent. An identifier is a name 

or number that identifies a category of users. The system uses identifiers to 
determine a user’s access to a resource. 


F$IDENTIFIER(identifier,conversion-type) 


Return Value 


Arguments 


Examples 


An integer value if you are converting an identifier from a name to an integer. 
The F$IDENTIFIER function returns a string if you are converting an identifier 
from an integer to a name. If you specify an identifier that is not valid, the 
F$IDENTIFIER function returns a null string ("") (if you are converting from 


~ number to name) or a zero (if you are converting from name to number). 


identifier 

Specifies the identifier to be converted. Specify the identifier as an integer 
expression if you are converting an integer to a name. Specify the identifier as a 
character string expression if you are converting a name to an integer. 


Any identifier holding the Name Hidden attribute will cause the FSIDENTIFIER 
to return an error when you do not hold the identifier in question or do not have 
access to the rights database. For further information on the attribute, see the 
OpenVMS Guide to System Security. 


conversion-type 

Indicates the type of conversion to be performed. If the identifier argument 
is alphanumeric, specify the conversion-type argument as a character string 
containing “NAME_TO_NUMBER’”. If the identifier argument is numeric, 
specify the conversion-type argument as a character string containing 
“NUMBER_TO_NAME”. 


1. $ UIC_INT= FSIDENTIFIER("SLOANE","NAME TO NUMBER") 
$ SHOW SYMBOL UIC_INT ‘ 
UIC_INT = 15728665 Hex = 00F00019 Octal = 00074000031 
$ UIC = F$FAO("!%U",UIC_INT) 
$ SHOW SYMBOL UIC 
UIC = [360,031] 


This example uses the F$SIDENTIFIER to convert the member identifier 
from the UIC [MANAGERS,SLOANE] to an integer. The FSIDENTIFIER 
function shows that the member identifier SLOANE is equivalent to the 
integer 15728665. Note that you must specify the identifier SLOANE using 
uppercase letters. 


To convert this octal number to a standard numeric user identification 

code (UIC), use the F$FAO function with the !%U directive. (This directive 
converts a longword to a UIC in named format.) In this example, the member 
identifier SLOANE is equivalent to the numeric UIC [860,031]. 
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2. 


$ UIC_INT = ($031 + (%X10000 * $0360)). 
$ UIC_NAME = FS$IDENTIFIER(UIC_INT,"NUMBER TO NAME") 
$ SHOW SYMBOL UIC_NAME 

UIC NAME = "ODONNELL" 


This example obtains the alphanumeric identifier associated with the numeric 
UIC [860,031]. First, you must obtain the longword integer that corresponds 
to the UIC [860,031]. To do this, place the member number into the low- 
order word. Place the group number into the high order word. Next, use the 
F$IDENTIFIER function to return the named identifier associated with the 
integer. 


FSINTEGER 


Format 
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FSINTEGER 


Returns the integer equivalent of the result of the specified expression. 


FSINTEGER(expression) . 


Return Value 


Argument 


Example 


An integer value that is equivalent to the specified expression. 


expression 
Specifies the expression to be evaluated. Specify either an integer or a character 
string expression. 


If you specify an integer expression, the F$SINTEGER function evaluates the 
expression and returns the result. If you specify a string expression, the 
F$INTEGER function evaluates the expression, converts the resulting string 
to an integer, and returns the result. 


After evaluating a string expression, the FSINTEGER function converts the result 
to an integer in the following way. If the resulting string contains characters that 
form a valid integer, the FSINTEGER function returns the integer value. If the 
string contains characters that do not form a valid integer, the FSINTEGER 
function returns the integer 1 if the string begins with T, t, Y, or y. The function 
returns the integer 0 if the string begins with any other character. 


"23" 

FSINTEGER("-9" + A) 

HOW SYMBOL B 

= -923 Hex=FFFFFC65 Octal=176145 


SA 
$B 
$ § 
B 


This example shows how to use the F$SINTEGER function to equate a symbol 

to the integer value returned by the function. In the example, the FSINTEGER 
function returns the integer equivalent of the string expression (“—9” + A). First, 
the FSINTEGER function evaluates the string expression by concatenating the 
string literal “—9” with the string literal “23”. Note that the value of the symbol A 
is substituted automatically in a string expression. Also note that the plus sign 
(+) is a string concatenation operator since both arguments are string literals. 


After the string expression is evaluated, the F$SINTEGER function converts the 
resulting character string (“—923”) to an integer, and returns the value —923. This 
integer value is assigned to the symbol B. 
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FSLENGTH 


Format 


Returns the length of the specified character string. 


F$LENGTH(string) 


Return Value 


Argument 


Example 
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An integer value for the length of the string. 


string 
Specifies the character string whose length is being determined. Specify the 
string argument as a character string expression. 


$ MESSAGE = FSMESSAGE($X1C) 
$ SHOW SYMBOL MESSAGE 
MESSAGE = "SSYSTEM-F-EXQUOTA, exceeded quota" 
$ STRING LENGTH = FSLENGTH (MESSAGE) 
$ SHOW SYMBOL STRING LENGTH 
STRING LENGTH = 33 Hex = 00000021 Octal = 000041 


The first assignment statement uses the FS{MESSAGE function to return the 
message that corresponds to the hexadecimal value 1C. The message is returned 
as a character string and is assigned to the symbol MESSAGE. 


The F$LENGTH function is then used to return the length of the character 
string assigned to the symbol MESSAGE. You do not need to use quotation marks 
(“”) when you use the symbol MESSAGE as an argument for the FSLENGTH 
function. (Quotation marks are not used around symbols in character string 
expressions.) 


The F$LENGTH function returns the length of the character string and assigns 
it to the symbol STRING_LENGTH. At the end of the example, the symbol 
STRING_LENGTH has a value equal to the number of characters in the value of 
the symbol named MESSAGE, that is, 33. 


FSLOCATE 


Format 


Lexical Functions 
FSLOCATE 


_ Locates a specified portion of a character string and returns as an integer the 


offset of the first character. (An offset is the position of a character or a substring 
relative to the begining of the string. The first character in a string is always 
offset position 0 from the beginning of the string.) If the substring is not found, 
F$LOCATE returns the length (the offset of the last character in the character 
string plus one) of the searched string. 


F$LOCATE(substring,string) 


Return Value 


Arguments 


Examples 


An integer value representing the offset of the substring argument. An offset is 
the position of a character or a substring relative to the beginning of the string. 
The first character in a string is always offset position 0 from the beginning of 
the string (which always begins at the leftmost character). 


If the substring is not found, the FSLOCATE function returns an offset of the last 
character in the character string plus 1. (This equals the length of the string.) 


substring 
Specifies the character string that you want to locate within the string specified 
in the string argument. 


string 
Specifies the character string to be edited by FSLOCATE. 


1. § FILE SPEC = "MYFILE.DAT;1" 
$ NAME LENGTH = FSLOCATE(".",FILE SPEC) 


The F$LOCATE function in this example returns the position of the period 
(.) in the string with respect to the beginning of the string. The period is in 
offset position 6, so the value 6 is assigned to the symbol NAME_LENGTH. 
Note that NAME_LENGTH also equals the length of the file name portion of 
the file specification MYFILE.DAT, that is, 6. 


The substring argument, the period, is specified as a string literal and is 
therefore enclosed in quotation marks (“”). The string argument FILE_ 
SPEC is a symbol, so it should not be placed within quotation marks. It 
is automatically replaced by its current value during the processing of the 
function. 
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$ INQUIRE TIME "Enter time" 
$ IF FSLOCATE(":",TIME) .EQ. FSLENGTH(TIME) THEN - 
GOTO NO_COLON 


This section of a command procedure compares the results of the FSLOCATE 
and F$LENGTH functions to see if they are equal. This technique is 
commonly used to determine whether a character or substring is contained in 
a string. 


In the example, the INQUIRE command prompts for a time value and assigns 
the user-supplied time to the symbol TIME. The IF command checks for the 
presence of a colon (:) in the string entered in response to the prompt. If 
the value returned by the FSLOCATE function equals the value returned by 
the FSLENGTH function, the colon is not present. You use the .EQ. operator 
(rather than .EQS.) because the FSLOCATE and F$LENGTH functions return 
integer values. 


Note that quotation marks are used around the substring argument, the 

colon, because it is a string literal. However, the symbol TIME does not 

require quotation marks because it is automatically evaluated as a string 
expression. 
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FSMESSAGE 


Format 


Returns as a character string the facility, severity, identification, and text 
associated with the specified system status code. 


F$MESSAGE(status-code[,message-component-list]) 


Return Value 


Arguments 


A character string containing the system message that corresponds to the 
argument you specify. 

Note that, although each message in the system message file has a numeric value 
or range of values associated with it, there are many possible numeric values 
that do not have corresponding messages. If you specify an argument that has 
no corresponding message, the FS|MESSAGE function returns a string containing 
the NOMSG error message. 


For more information on system error messages, see the OpenVMS System 
Messages: Companion Guide for Help Message Users. 


status-code 
Specifies the status code for which you are requesting error message text. You 
must specify the status code as an integer expression. 


message-component-list 

Specifies the system message component for which information is to be returned. 
If this parameter is null or unspecified, then all system message components are 
returned. 


Table DCLI-14 describes the valid system message component keywords: 


Table DCLI-14 FSMESSAGE Keywords 


Component Keyword Information returned 
FACILITY Facility name 

SEVERITY Severity level indicator 
IDENT Abbreviation of message text 
TEXT Explanation of message 


Note that when the FACILITY, SEVERITY, and IDENT code keywords are 
specified (individually or in combination), the resulting message code is prefaced 
with the percent (%) character. The individual parts of the message code are 
separated by hyphens when multiple code keywords are specified. 


When only the TEXT keyword is specified, the resulting text is not prefaced 
with any character. When the TEXT keyword is specified with the FACILITY, 
SEVERITY, or IDENT code keyword, the message code is separated from the text 
by a combination of a comma and a blank (, ). 
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Example 


DCLI-384 


$ ERROR _TEXT = FSMESSAGE(%X1C) 
$ SHOW SYMBOL ERROR TEXT 
ERROR_TEXT = "SSYSTEM-F-EXQUOTA, exceeded quota" 


This example shows how to use the FSMESSAGE function to determine the 
message associated with the status code %X1C. The FS/{MESSAGE function 
returns the message string, which is assigned to the symbol ERROR_TEXT. 


$ SUBMIT IMPORTANT.COM 

$ SYNCHRONIZE /entry='SENTRY’ 

$ IF $STATUS THEN EXIT 

$! 

$ JOB_STATUS = $STATUS 
I 


$ IF "$JOBDELETE" .EQS. FSMESSAGE (JOB STATUS, "IDENT") 


$ THEN 

$ ELSE 

$ IF "JOBABORT" .EQS. FSMESSAGE (JOB STATUS, "IDENT") 
$ THEN 

$ ELSE 

$ e 

$ ENDIF 


$ ENDIF 


This command procedure submits a batch job and waits for it to complete. Upon 
successful completion, the procedure exits. If the job completes unsuccessfully, 
more processing is done based on the termination status of the batch job. 


The first command submits the command procedure IMPORTANT.COM. In the 
second command, the SYNCHRONIZE command tells the procedure to wait for 
the job to finish. The third command determines if the job completed successfully 
and, if so, the procedure exits. The next command saves the status in a symbol. 


The first IF statement uses F$MESSAGE to determine whether the job was 
deleted before execution. If so, it does some processing, possibly to resubmit the 


job or to inform a user via MAIL. 


The next IF statement uses F$MESSAGE to determine whether the job was 
deleted during execution. As a result, some cleanup or human intervention may 
be required, which would be done in the THEN block. 


If neither IF statement was true, then some other unsuccessful status was 
returned. Other processing, which would be done in the block following the ELSE 
statement, might be required. 


FSMODE 


Format 
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FSMODE 


Returns a character string showing the mode in which a process is executing. 
The F$MODE function has no arguments, but must be followed by parentheses. 


F$MODE() 


Return Value 


Arguments 


Description 


Example 


The character string INTERACTIVE for interactive processes. If the process is 
noninteractive, the character string BATCH, NETWORK or OTHER is returned. 
Note that the return string always contains uppercase letters. 


None. 


The lexical function FSMODE returns a character string showing the mode in 
which a process is executing. The F${MODE function has no arguments, but must 
be followed by parentheses. 


The F$MODE function is useful in command procedures that must operate 
differently when executed interactively and noninteractively. You should include 
either the FSMODE function or the FSENVIRONMENT function in your login 
command file to execute different commands for interactive terminal sessions and 
noninteractive sessions. 


If you do not include the F$MODE function to test whether your login command 
file is being executed from an interactive process, and the login command file is 
executed from a noninteractive process (such as a batch job), the process may 
terminate if the login command file contains commands that are appropriate only 
for interactive processing. 


A command procedure can use the FS{MODE function to test whether the 
procedure is being executed during an interactive terminal session. It can direct 
the flow of execution according to the results of this test. 


$ IF F$MODE() .NES. "INTERACTIVE" THEN GOTO NON_INT DEF 


$ INTDEF: ! Commands for interactive terminal sessions 
$ EXIT 
$ NON_INT DEF: !Commands for noninteractive processes 


This example shows the beginning of a login.com file that has two sets of 
initialization commands: one for interactive mode and one for noninteractive 
mode (including batch and network jobs). The IF command compares the 
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character string returned by F$MODE with the character string INTERACTIVE; 
if they are not equal, control branches to the label NON_INT_DEF. If the 

- character strings are equal, the statements following the label INTDEF are 
executed and the procedure exits before the statements at NON_INT_DEF. 


DCLI-386 


FSPARSE 


Format 
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Parses a file specification and returns either the expanded file specification or the 
particular file specification field that you request. 


FSPARSE (filespec [,default-spec] [,related-spec] [,field] [,parse-type]) 


Return Value 


Arguments 


A character string containing the expanded file specification or the field you 
specify. If you do not provide a complete file specification for the filespec 
argument, the F$PARSE function supplies defaults in the return string. For more 
information, see the Description section for this lexical function. 

In most cases, the F$PARSE function returns a null string ("") if an error is 
detected during the parse. For example, a null string is returned if the file 
specification has incorrect syntax or if a disk or directory does not exist, making 
the file specification logically incorrect. However, when you specify a field name 


~ or the SYNTAX_ONLY parse type, F$PARSE returns the appropriate information. 


filespec 
Specifies a character string containing the file specification to be parsed. 


The file specification can contain the asterisk (*) and the percent sign (%) 
wildcard characters. If you use a wildcard character, the file specification 
returned by the F$PARSE function contains the wildcard. 


default-spec 
Specifies a character string containing the default file specification. 


The fields in the default file specification are substituted in the output string 
if a particular field in the filespec argument is missing. You can make further 
substitutions in the filespec argument by using the related-spec argument. 


related-spec 
Specifies a character string containing the related file specification. 


The fields in the related file specification are substituted in the output string if a 
particular field is missing from both the filespec and default-spec arguments. 


field 

Specifies a character string containing the name of a field in a file specification. 
Specifying the field argument causes the F$PARSE function to return a specific 
portion of a file specification. 


Specify one of the following field names (do not abbreviate): 


NODE Node name 
DEVICE Device name 
DIRECTORY Directory name 
NAME File name 
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TYPE File type 
VERSION File version number 
parse-type 


Specifies the type of parsing to be performed. By default, the FSPARSE function 
verifies that the directory in the file specification exists on the device in the file 
specification. However, the existence of the directory is not verified if you provide 
a field argument. Note that the device and directory can be explicitly given in 

one of the arguments, or can be provided by default. 


Also, by default the F$PARSE function translates logical names if they are 
provided in any of the arguments. The F$PARSE function stops iterative 
translation when it encounters a logical name with the CONCEALED attribute. 


You can change how the F$PARSE function parses a file specification by using 
one of the following keywords: 


NO_CONCEAL Ignores the “conceal” attribute in the translation of a logical 
name as part of the file specification; that is, logical name 
translation does not end when a concealed logical name is 
encountered. 


SYNTAX_ONLY The syntax of the file specification is checked without 
verifying that the specified directory exists on the specified 
device. 


The F$PARSE function parses file specifications by using the RMS service 
$PARSE. For more information on the $PARSE service, see the OpenVMS Record 
Management Services Reference Manual. 


When you use the F$PARSE function, you can omit those optional arguments to 
the right of the last argument you specify. However, you must include commas 
(,) as placeholders if you omit optional arguments to the left of the last argument 
you specify. 


If you omit the device and directory names in the filespec argument, the 
F$PARSE function supplies defaults, first from the default-spec argument and 
second from the related-spec argument. If names are not provided by these 
arguments, the F$PARSE function uses your current default disk and directory. 


If you omit the node name, the file name, the file type, or the version number, the 
F$PARSE function supplies defaults, first from the default-spec argument and 
second from the related-spec argument. (Note that the version number is not 
picked up from the related-spec argument.) If names are not provided by these 
arguments, the F$PARSE function returns a null specification for these fields. 


1. §$ SET DEF DISK2:[FIRST] 
$ SPEC = FSPARSE("JAMES.MAR","{ROOT]",,,"SYNTAX ONLY") 
$ SHOW SYMBOL SPEC ~ 
SPEC = "DISK2:[ROOT]JAMES.MAR;" 


In this example, the FSPARSE function returns the expanded file specification 
for the file JAMES.MAR. The example uses the SYNTAX_ONLY keyword 

to request that FSPARSE check the syntax, but should not verify that the 
[ROOT] directory exists on DISK2. 


Lexical Functions 
-FSPARSE 


The default device and directory are DISK2:[FIRST]. Because the directory 
name [ROOT] is specified as the default-spec argument in the assignment 
statement, it is used as the directory name in the output string. Note that the 
default device returned in the output string is DISK2, and the default version 
number for the file is null. You must place quotation marks (“”) around the 
arguments JAMES.MAR and ROOT because they are string literals. 


If you had not specified syntax-only parsing, and nOOT were not on DISK2, 
a null string would have been returned. 


$ SET DEFAULT DB1: [VARGO] 
$ SPEC = FSPARSE("INFO.COM",,, "DIRECTORY" ) 
$ SHOW SYMBOL SPEC 

SPEC = "[VARGO]" 


In this example the F$PARSE function returns the directory name of the 
file INFO.COM. Note that because the default-spec and related-spec 
arguments are omitted from the argument list, commas (,) must be inserted 
in their place. 


$ SPEC= FSPARSE( "DENVER: :DB1:[PROD]RUN.DAT",,,"TYPE") 
$ SHOW SYMBOL SPEC 
SPEC = ".DAT" 


In this example, the FSPARSE function is used to parse a file specification 
containing a node name. The F$PARSE function returns the file type .DAT 
for the file RUN.DAT at the remote node DENVER. 
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F$PID 


Format 


Returns a process identification (PID) number and updates the context symbol to 
point to the current position in the system’s process list. 


F$PID(context-symbol) 


Return Value 


Argument 


Description 
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A character string containing the PID of a process in the system’s list of processes. 


context-symbol 
Specifies a symbol that DCL uses to store a pointer into the system’s list of 
processes. The F$PID function uses this pointer to return a PID. 


Specify the context symbol by using a symbol. The first time you use the 
F$PID function in a command procedure, you should use a symbol that is either 
undefined or equated to the null string ("") or a context symbol that has been 
created by the FSCONTEXT function. 


If the context symbol is undefined or equated to a null string, the F$PID function 
returns the first PID in the system’s process list that it has the privilege to 
access. That is, if you have GROUP privilege and if the context symbol is null or 
undefined, the F$PID function returns the PID of the first process in your group. 
If you have WORLD privilege, the F$PID function returns the PID of the first 
process in the list. If you have neither GROUP nor WORLD privilege, the F$PID 
returns the first process that you own. Subsequent calls to F$PID return the rest 
of the processes on the system you are accessing. 


If the context symbol has been created by the FSCONTEXT function, the F$PID 
function returns the first process name in the system’s process list that fits the 
criteria specified in the FSCONTEXT calls. Subsequent calls to F$PID return 
only the PIDs of those processes that meet the selection criteria set up by the 
F$CONTEXT function and that are accessible to your current privileges. 


The F$PID function returns a process identification (PID) number and updates 
the context symbol to point to the current position in the system’s process list. 
You can step through all the processes on a system, or use the lexical function 
F$CONTEXT to specify selection criteria. The function FSCONTEXT is not 
required. 


The PIDs returned by the F$PID function depend on the privilege of your process. 
If you have GROUP privilege, the F$PID function returns PIDs of processes in 
your group. If you have WORLD privilege, the F$PID function returns PIDs of 
all processes on the system. If you lack GROUP or WORLD privilege, the F$PID 
function returns only those processes that you own. 


The FS$CONTEXT function enables the F$PID function to retrieve processes from 
any node in a dual-architecture VMScluster system. 


Example 


Lexical Functions 
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The first time you use the F$PID function, use a symbol that is either undefined 
or equated to the null string or to a context symbol that has been created by the 

F$CONTEXT function. This causes the F$PID function to return the first PID in 
the system’s process list that you have the privilege to access. It also causes the 

F$PID function to initialize the context-symbol argument. 


Once the context-symbol argument is initialized, each subsequent F$PID 
returns the next PID in sequence, using the selection criteria set up by the 
F$CONTEXT function, if any, and updates the context symbol. After the last PID 
in the process list is returned, the F$PID function returns a null string. 


$ CONTEXT = "" 

$ START: 

$ PID = FS$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 
$ SHOW SYMBOL PID 

$ GOTO START 


This command procedure uses the F$PID function to display a list of PIDs. 
The assignment statement declares the symbol CONTEXT, which is used as 
the context-symbol argument for the F$PID function. Because CONTEXT is 
equated to a null string, the F$PID function returns the first PID in the process 
list that it has the privilege to access. 


The PIDs displayed by this command procedure depend on the privilege of your 
process. When run with GROUP privilege, the PIDs of users in your group are 
displayed. When run with WORLD privilege, the PIDs of all users on the system 
are displayed. Without GROUP or WORLD privilege, only those processes that 
you own are displayed. 
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FS$PRIVILEGE 


Format 


Returns a string value of either TRUE or FALSE, depending on whether your 
current process privileges match those specified in the argument. You can specify 
either the positive or negative version of a privilege. 


F$PRIVILEGE(priv-states) 


Return Value 


Arguments 


Description 


Example 
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A character string containing the value TRUE or FALSE. The F$PRIVILEGE 
function returns the string FALSE if any one of the privileges in the priv-states 
argument list is false. 


priv-states 

Specifies a character string containing a privilege, or a list of privileges separated 
by commas (, ). For a list of process privileges, see the OpenVMS Guide to System 
Security. Specify any one of the process privileges except [NOJALL. 


Use the F$PRIVILEGE function to identify your current process privileges. 


If “NO” precedes the privilege, the privilege must be disabled in order for the 
function to return a value of TRUE. The F$PRIVILEGE function checks each of 
the keywords in the specified list, and if the result for any one is false, the string 
FALSE is returned. 


$ PROCPRIV = FS$PRIVILEGE( "OPER, GROUP, TMPMBX , NONETMBX" ) 
$ SHOW SYMBOL PROCPRIV 
PROCPRIV = "FALSE" 


The F$PRIVILEGE function is used to test whether the process has OPER, 
GROUP, and TMPMBX privileges and if you do not have NETMBX privileges. 


The process in this example has OPER (operator), GROUP, TMPMBX (temporary 
mailbox), and NETMBX (network mailbox) privileges. Therefore, a value of 
FALSE is returned because the process has NETMBX privilege, but NONETMBX 
was specified in the priv-states list. Although the Boolean result for the other 
three keywords is true, the entire expression is declared false because the result 
for NONETMBX was false. 
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FSPROCESS 


Obtains the current process name string. The F$PROCESS function has no 
arguments, but must be followed by parentheses. 

Format 
FEPROCESS() 


Return Value 


A character string containing the current process name. 
Arguments 


None. 


Example 


$ NAME = FSPROCESS() 
$ SHOW SYMBOL NAME 
NAME = "MARTIN" 


In this example, the FSPROCESS function returns the current process name and 
assigns it to the symbol NAME. 
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Searches a directory file and returns the full file specification for a file you specify. 


Format 
FESEARCH(filespec[,stream-id]) 


Return Value 


A character string containing the expanded file specification for the filespec 
argument. If the FSSEARCH function does not find the file in the directory, the 
function returns a null string (""). 


Arguments 


filespec 

Specifies a character string containing the file specification to be searched for. If 
the device or directory names are omitted, the defaults from your current default 
disk and directory are used. The FSSEARCH function does not supply defaults 
for a file name or type. If the version is omitted, the specification for the file with 
the highest version number is returned. If the filespec argument contains the 
asterisk (*) or the percent sign (% ) wildcard characters, each time FSSEARCH 
is called, the next file specification that agrees with the filespec argument is 
returned. A null string is returned after the last file specification that agrees 
with the filespec argument. 


stream-id 
Specifies a positive integer representing the search stream identification number. 


The search stream identification number is used to maintain separate search 
contexts when you use the F$SEARCH function more than once and when 
you supply different filespec arguments. If you use the FSSEARCH function 
more than once in a command procedure and if you also use different filespec 
arguments, specify stream-id arguments to identify each search separately. 


If you omit the stream-id argument, the F$SEARCH function starts searching 
at the beginning of the directory file each time you specify a different filespec 
argument. 


Description 


The lexical function FSSEARCH invokes the RMS service $SEARCH to search 
a directory file and return the full file specification for a file you specify. The 
F$SEARCH function allows you to search for files in a directory by using the 
RMS service $SEARCH. For more information on the $SEARCH routine, see the 
OpenVMS Record Management Services Reference Manual. 


You can use the F$SEARCH function in a loop in a command procedure to return 
file specifications for all files that match a filespec argument containing an 
asterisk (*) or a percent sign (% ) wildcard character. Each time the FSSEARCH 
function is executed, it returns the next file specification that matches the file 
specification that contains a wildcard character. After the last file specification 
is returned, the next F$SEARCH call returns a null string. When you use 

the FS6SEARCH function in a loop, you must include an asterisk (*) and the 
percent sign (%) wildcard characters in the filespec argument. Otherwise, the 
F$SEARCH always returns the same file specification. 
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Note that you must maintain the context of the search stream in one of the 
following ways: 


e Explicitly, by stating a stream-id argument 


¢ Implicitly, by omitting the stream-id argument and by using the same 
filespec argument each time you execute the FSSEARCH function 


If you do not maintain the context of the search stream, you start a new search 
at the beginning of the directory file each time you specify a different filespec 
argument. 


Note 


The lexical function F$SEARCH can return any file that matches the 
selection criteria you specify, and that exists in the directory at some time 
between the beginning and the end of the search. Files that are created, 
renamed, or deleted during the search may or may not be returned. 


$ START: 

$ FILE = FSSEARCH("SYSSSYSTEM:*.EXE") 
$ IF FILE .EQS. "" THEN EXIT 

$ SHOW SYMBOL FILE 

$ GOTO START 


This command procedure displays the file specifications of the latest version 
of all .EXE files in the SYS$SYSTEM directory. (Only the latest version 

is returned because an asterisk (*) wildcard character is not used as the 
version number.) The filespec argument SYS$SYSTEM:*.EXE is surrounded 
by quotation marks (“”) because it is a character string expression. 


Because no stream-id argument is specified, the FSSEARCH function uses 
a single search stream. Each subsequent F$SEARCH call uses the same 
filespec argument to return the next file specification of an .EXE file from 
SYS$SYSTEM:. After the latest version of each .EXE file has been displayed, 
the F$SEARCH function returns a null string ("") and the procedure exits. 


2. $ START: 
$ COM = FSSEARCH ("*.COM;*",1) 
$ DAT = FSSEARCH ("*.DAT;*",2) 
$ SHOW SYMBOL COM 
$ SHOW SYMBOL DAT 
$ IF (COM.EQS. "") .AND. (DAT.EQS. "") THEN EXIT 


$ GOTO START 


This command procedure searches the default disk and directory for both 
.COM and .DAT files. Note that the stream-id argument is specified for each 
F$SEARCH call so that the context for each search is maintained. 


The first FSSEARCH call starts searching from the top of the directory 

file for a file with a type .COM. When it finds a .COM file, a pointer is set 

to maintain the search context. When the FSSEARCH function is used 

the second time, it again starts searching from the top of the directory file 
for a file with a type .DAT. When the procedure loops back to the label 
START, the stream-id argument allows F$SEARCH to start searching in the 
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correct place in the directory file. After all versions .COM and .DAT files are 
returned, the procedure exits. 


$ FILESPEC = FSSEARCH("TRNTO""SMITH SALLY"": :DBA1:[PROD]*.DAT") 
$ SHOW SYMBOL FILESPEC . 
FILESPEC = "TRNTO"smith password": :DBA1:[PROD]CARS.DAT" 


This example uses the F$SEARCH function to return a file specification for a 
file at a remote node. The access control string is enclosed in quotation marks 
because it is part of a character string expression when it is an argument for 
the FS{SEARCH function. To include quotation marks in a character string 
expression, you must use two sets of quotation marks. 


Note that, when the F${SEARCH function returns a node name containing an 
access control string, it substitutes the word “password” for the actual user 
password. 


Lexical Functions 
FSSETPRV 


FSSETPRV 


Enables or disables specified user privileges. The F$SETPRV function returns 
a list of keywords indicating user privileges; this list shows the status of the 
specified privileges before FS{SETPRV was executed. 


Your process must be authorized to set the specified privilege. 


For detailed information on privilege restrictions, see the description of the 
$SETPRV system service in the OpenVMS System Services Reference Manual. 


Format 
FSSETPRV(priv-states) 


Return Value 


A character string containing keywords for the current process privileges before 
they were changed by the F$SETPRV function. 


Argument 


priv-states 
Specifies a character string defining a privilege, or a list of privileges separated 
by commas (,). 


For a list of process privileges, see the OpenVMS User’s Manual. 


Description 


The lexical function F${SETPRV invokes the $SETPRV system service to enable 
or disable specified user privileges. The F$SETPRV function returns a list of 
keywords indicating user privileges; this list shows the status of the specified 
privileges before FSSETPRV was executed. 


The F$SETPRV function returns keywords for your current privileges, whether 
or not you are authorized to change the privileges listed in the priv-states 
argument. However, the F$SETPRV function enables or disables only the 
privileges you are authorized to change. 


When you run programs or execute procedures that include the FSSETPRV 
function, be sure that FSSETPRV restores your process to its proper privileged 
state. For additional information, refer to the examples that follow. 


Examples 


1. $ OLDPRIV = FSSETPRV( "OPER, NOTMPMBX" ) 
$ SHOW SYMBOL OLDPRIV 
OLDPRIV = "NOOPER, TMPMBX" 


In this example, the process is authorized to change the OPER (operator) and 
TMPMBX (temporary mailbox) privileges. The F$SETPRV function enables 
the OPER privilege and disables the TMPMBX privilege. In addition, the 
F$SETPRV function returns the keywords NOOPER and TMPMBX, showing 
the state of these privileges before they were changed. 


You must place quotation marks (“”) around the list of privilege keywords 
because it is a string literal. 
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2. 


$ SHOW PROCESS/PRIVILEGE 
14-DEC-1994 15:55:09.60  RTAIL: User: SMITH 
Process privileges: 


Process rights identifiers: 
INTERACTIVE 
LOCAL 


$ NEWPRIVS = FSSETPRV("ALL, NOOPER") 
$ SHOW SYMBOL NEWPRIVS 
NEWPRIVS = "NOCMKRNL, NOCMEXEC , NOSYSNAM, NOGRPNAM, NOALLSPOOL, 

NODETACH ,NODIAGNOSE, NOLOG_IO,NOGROUP, NOACNT, NOPRMCEB , NOPRMMBX, 
NOPSWAPM, NOALTPRI, NOSETPRV , NOTMPMBX , NOWORLD , NOMOUNT, NOOPER, 
NOEXQUOTA , NONETMBX , NOVOLPRO, NOPHY_IO,NOBUGCHK, NOPRMGBL, 
NOSYSGBL, NOPFNMAP , NOSHMEM, NOSYSPRV, NOBYPASS , NOSYSLCK, NOSHARE, 
NOUPGRADE , NODOWNGRADE , NOGRPPRV , NOREADALL , NOSECURITY , OPER" 

$ SHOW PROCESS/PRIVILEGE 


14-DEC-1994 10:21:18.32 User: METCALFE Process ID: 00000F24 
Node: TOKNOW Process name: "_FTA23;" 


Authorized privileges: 
NETMBX SETPRV SYSPRV TMPMBX 


Process privileges: 


ACNT May suppress accounting messages 

ALLSPOOL may allocate spooled device 

ALTPRI may set any priority value 

AUDIT may direct audit to system security audit log 
BUGCHK may make bug check log entries 

BYPASS may bypass all object access controls 
CMEXEC may change mode to exec 

CMKRNL may change mode to kernel 

DETACH . May create detached processes 

DIAGNOSE may diagnose devices 

DOWNGRADE may downgrade object secrecy 

EXQUOTA ' may exceed disk quota 

GROUP may affect other processes in same group 
GRPNAM may insert in group logical name table 
GRPPRV May access group objects via system protection 
IMPORT ’ may set classification for unlabeled object 
LOG I0 may do logical i/o 

MOUNT May execute mount acp function 

NETMBX May create network device 

OPER may perform operator functions 

PFNMAP May map to specific physical pages 

PHY 10 may do physical i/o 

PRMCEB May create permanent common event clusters 
PRMGBL May create permanent global sections 

PRMMBX - may create permanent mailbox 

PSWAPM May change process swap mode 

READALL may read anything as the owner 

SECURITY may perform security administration functions 
SETPRV May set any privilege bit 

SHARE May assign channels to non-shared devices 
SHMEM may create/delete objects in shared memory 
_SYSGBL may create system wide global sections 
SYSLCK  _ may lock system wide resources 

SYSNAM may insert in system logical name table 
SYSPRV May access objects via system protection 
TMPMBX May create temporary mailbox 

UPGRADE may upgrade object integrity 

VOLPRO May override volume protection 


WORLD may affect other processes in the world 
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Process rights: 
INTERACTIVE 
LOCAL 


System rights: 
SYSSNODE_TOKNOW 


$ NEWPRIVS = FSSETPRV (NEWPRIVS) 
$ SHOW PROCESS/PRIVILEGE 


14-DEC-1994 16:05:07.23 RTAI1: User: METCALFE 
Process privileges: 

OPER operator privilege 
Process rights identifiers: 

INTERACTIVE 

LOCAL 


In this example, the DCL command SHOW PROCESS/PRIVILEGE is used 
to determine the current process privileges. Note that the process has no 
privileges enabled. 


The F$SETPRV function is then used to process the ALL keyword and enable 
all privileges recording the previous state of each privilege in the symbol 
NEWPRIVS. Next, FSSETPRV processes the NOOPER keyword and disables 
the OPER (operator) privilege, recording the previous state of OPER in 
NEWPRIVS. Note that the OPER privilege appears in the returned string 
twice: first as NOOPER and then as OPER. 


Entering the command SHOW PROCESS/PRIVILEGE now shows that the 
current process has all privileges enabled except OPER. 


If the returned string is used as the parameter to F$SETPRYV, the process 
has the OPER privilege enabled. This occurs because the OPER command 
was present twice in the symbol NEWPRIVS. As a result, FSSETPRV looked 
at the first keyword NOOPER and disabled the privilege. Finally, after 
processing several other keywords in the NEWPRIVS string, the OPER 
keyword is presented, allowing F$SETPRV to enable the OPER privilege.. 


If you are using the ALL or NOALL keywords to save your current privilege 
environment, Digital recommends that you perform the following procedure to 
modify the process for a command procedure: 


$ CURRENT PRIVS = FSSETPRV("ALL") 
$ TEMP = FSSETPRV("NOOPER") 


If you use this procedure, you can then specify the following command 
statement at the end of your command procedure so that the original privilege 
environment is restored: 


$ TEMP = FSSETPRV(CURRENT PRIVS) 


$ SAVPRIV = FSSETPRV("NOGROUP") 
$ SHOW SYMBOL SAVPRIV 
SAVPRIV = "GROUP" 
$ TEST = FS$PRIVILEGE("GROUP") 
$ SHOW SYMBOL TEST 
TEST = "TRUE" 


In this example, the process is not authorized to change the GROUP privilege. 
However, the F${SETPRV function still returns the current setting for the 
GROUP privilege. 
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The F$PRIVILEGE function is used to see whether the process has GROUP 
privilege. The return string, TRUE, indicates that the process has GROUP 
privilege, even though the F$SETPRV function attempted to disable the 
privilege. 


$ SHOW PROCESS/PRIVILEGE 


14-DEC-1994 15:55:09.60  RTAI1: User: METCALFE 

Process privileges: 

AUDIT may direct audit to system security audit log 
DOWNGRADE may downgrade object secrecy 

IMPORT may set classification for unlabeled object 
UPDATE 


These process privileges are VAX specific and are used only in Security . 
Enhancement Service Software (SEVMS) on an OpenVMS VAX system. 


FSSTRING 


Format 
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Returns the string that is equivalent to the specified expression. 


_FSSTRING(expression) 


Return Value 


Argument 


Example 


A character string equivalent to the specified expression. 


expression 
The integer or string expression to be evaluated. 


If you specify an integer expression, the F$STRING function evaluates the 
expression, converts the resulting integer to a string, and returns the result. If 
you specify a string expression, the F${STRING function evaluates the expression 
and returns the result. 


When converting an integer to a string, the FSSTRING function uses decimal 
representation and omits leading zeros. When converting a negative integer, the 
F$STRING function places a minus sign at the beginning string representation of 
the integer. 


5 

FSSTRING(-2 + A) 
HOW SYMBOL B 

B = w3e 


The F$STRING function in this example converts the result of the integer 
expression (—2 + A) to the numeric string, “3”. First, the FSSTRING function 


evaluates the expression (-2 + A). Note that 5, the value of symbol A, is 
automatically substituted when the integer expression is evaluated. 


SA 
$B 
$ S 


After the integer expression is evaluated, the FSSTRING function converts the 
resulting integer, 3, to the string “3”. This string is assigned to the symbol B. 
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Format 


Returns the current date and time in absolute time format. 


The F$TIME function has no arguments, but must be followed by parentheses. 


FSTIME() 


Return Value 


Arguments 


Example 
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A character string containing the current date and time. The returned string has 
the following fixed, 23-character format: 
dd-mmm-yyyy hh:mm:ss.cc 


When the current day of the month is any of the values 1 to 9, the first character 
in the returned string is a blank character. The time portion of the string is 
always in character position 13, at an offset of 12 characters from the beginning 
of the string. . 


Note that you must use the assignment operator (=) to preserve the blank 
character in the returned string. If you use the string assignment operator (:=), 
the leading blank is dropped. 


None. 


$ OPEN/WRITE OUTFILE DATA.DAT 
$ TIME STAMP = F$TIME() 
$ WRITE OUTFILE TIME STAMP 


This example shows how to use the F$TIME function to time-stamp a file that 
you create from a command procedure. OUTFILE is the logical name for the 

file DATA.DAT, which is opened for writing. The F$TIME function returns the 
current date and time string, and assigns this string to the symbol TIME_STAMP. 
The WRITE command writes the date and time string to OUTFILE. 


FSTRNLNM 


Format 
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Translates a logical name and returns the equivalence name string or the 
requested attributes of the logical name specified. 


FETRNLNM(logical-name [,table] [,index] [,mode] [,case] [,item]) | 


Return Value 


Arguments 


The equivalence name or attribute of the specified logical name. The return 
value can be a character string or an integer, depending on the arguments you 
specify with the FSTRNLNM function. If no match is found, a null string ("") is 
returned. 


logical-name 
Specifies a character string containing the logical name to be translated. 


table 

Specifies a character string containing the logical name table or tables that the 
F$TRNLNM function should search to translate the logical name. The table 
argument must be a logical name that translates to a logical name table or to a 
list of table names. 


Note 


If you subsequently create a table using the CREATE/NAME TABLE _. 
command and want to make your private table accessible for FSTRNLNM, 
you must redefine one of the table logical names to include your private 
table. To see all the tables that are normally searched by F$STRNLNM, 
issue the following command: 


$ SHOW LOGICAL/STRUCTURE LNM$DCL_ LOGICAL 


For more information, see the CREATE/NAME_TABLE amd SHOW 
LOGICAL commands. 


If you do not specify a table, the default value is LNM$DCL_LOGICAL. That 

is, the F$STRNLNM function searches the tables whose names are equated to 
the logical name LNM$DCL_LOGICAL. Unless LNM$DCL_LOGICAL has been 
redefined for your process, the FSTRNLNM function searches the process, job, 
group, and system logical name tables, in that order, and returns the equivalence 
name for the first match found. 


index 

Specifies the number of the equivalence name to be returned if the logical name 
has more than one translation. The index refers to the equivalence strings in the 
order the names were listed when the logical name was defined. 


The index begins with zero; that is, the first name in a list of equivalence names 
is referenced by the index zero. 


If you do not. specify the index argument, the default is zero. 
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mode 


Specifies a character string containing one of the following access modes for the 
translation: USER (default), SUPERVISOR, EXECUTIVE, or KERNEL. 


The F$TRNLNM function starts by searching for a logical name created with 
the access mode specified in the mode argument. If it does not find a match, 
the F$TRNLNM function searches for the name created with each inner access 
mode and returns the first match found. For example, two logical names can 
have the same name, but one name can be created with user access mode and 
the other name with executive access mode. If the mode argument is USER, the 
F$TRNLNM function returns the equivalence string for the user-mode, not the 
executive-mode, logical name. 


case 

Specifies the type of case translation to be performed. Specify the case argument 
as either of the following character strings: CASE_BLIND (default) or CASE_ 
SENSITIVE. 


If the translation is case blind, the FSTRNLNM function first searches for a 
logical name with characters of the same case as the logical-name argument. If 
no match is found, the FSTRNLNM function searches for an uppercase version of 
the logical-name argument and the logical names it is searching. The result of 
the first successful translation is returned. 


If the translation is case sensitive, the FSTRNLNM function searches only for a 
logical name with characters of the same case as the logical-name argument. If 
no exact match is found, the FSTRNLNM function returns a null string ((""). 


item 
Specifies a character string containing the type of information that F$STRNLNM 
should return about the specified logical name. Specify one of the following items: 


Item Return Type Information Returned 

ACCESS_ String One of the following access modes associated 

MODE with the logical name: USER, SUPERVISOR, 
EXECUTIVE, KERNEL. 

CONCEALED String TRUE or FALSE to indicate whether the 


CONCEALED attribute was specified with 
the /TRANSLATION_ATTRIBUTES qualifier 
when the logical name was created. The 
CONCEALED attribute is used to create a 
concealed logical name. 


CONFINE String TRUE or FALSE to indicate whether the 
logical name is confined. If the logical name is 
confined (TRUE), then the name is not copied 
to subprocesses. If the logical name is not 
confined (FALSE), then the name is copied to 
subprocesses. 


Item 


CRELOG 


LENGTH 


~ MAX INDEX 


NO_ALIAS 


TABLE 


TABLE_NAME 


- TERMINAL 


Description 


VALUE 


Return Type 


String 


Integer 


Integer 


String 


String 


_ ‘String 


String 


String 
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Information Returned 


TRUE or FALSE to indicate whether the 
logical name was created with the $CRELOG 
system service or with the $CRELNM system 
service, using the CRELOG attribute. 

If the logical name was created with the 
$CRELOG system service or with the 
$CRELNM system service, using the CRELOG 
attribute, then TRUE is returned. Otherwise, 
FALSE is returned. . 


Length of the equivalence name associated 
with the specified logical name. If the logical 
name has more than one equivalence name, 
the FSTRNLNM function returns the length of 
the name specified by the index argument. 


The largest index defined for the logical name. 
The index shows how many equivalence names 
are associated with a logical name. The index 
is zero based; that is, the index zero refers to 
the first name in a list of equivalence names. 


TRUE or FALSE to indicate whether the 
logical name has the NO_ALIAS attribute. 
The NO_ALIAS attribute means that a logical 
name must be unique within outer access 
mode. 


TRUE or FALSE to indicate whether the 
logical name is the name of a logical name 
table. 


Name of the table where the logical name was 
found. 


TRUE or FALSE to indicate whether the 
TERMINAL attribute was specified with the 
/TRANSLATION_ATTRIBUTES qualifier 
when the logical name was created. The 
TERMINAL attribute indicates that the 
logical name is not a candidate for iterative 
translation. 


Default. The equivalence name associated 
with the specified logical name. If the logical 
name has more than one equivalence name, 
the F$STRNLNM function returns the name 
specified by the index argument. 


The lexical function FSTRNLNM uses the $TRNLNM system service to translate 
a logical name and return the equivalence name string, or the requested 
attributes of the logical name specified. The translation is not iterative; the 
equivalence string is not checked to determine whether it is a logical name. 
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When you use the F$STRNLNM function, you can omit optional arguments that 
can be used to the right of the last argument you specify. However, you must 
include commas (,) as placeholders if you omit optional arguments to the left of 
the last argument that you specify. 


You can use the F$STRNLNM function in command procedures to save the current 
equivalence of a logical name and later restore it. You can also use it to test 
whether logical names have been assigned. 


1. 


$ SAVE_DIR = FSTRNLNM("SYSSDISK" )+FSDIRECTORY ( ) 


$ SET DEFAULT 'SAVE_DIR’ 


The assignment statement concatenates the values returned by the 
F$DIRECTORY and F$TRNLNM functions, and assigns the resulting string 
to the symbol SAVE_DIR. The symbol SAVE_DIR consists of a full device and 
directory name string. 


The argument SYS$DISK is enclosed in quotation marks (“”) because it 

is a character string. (The command interpreter treats all arguments that 
begin with alphabetic characters as symbols or lexical functions, unless the 
arguments are enclosed in quotation marks.) None of the optional arguments 
is specified, so the FSTRNLNM function uses the defaults. 


At the end of the command procedure, the original default directory is reset. 
When you reset the directory, you must place single quotation marks (‘’ ) 
around the symbol SAVE_DIR to force symbol substitution. 


$ DEFINE/TABLE=LNMSGROUP TERMINAL ‘FSTRNLNM("SYSSOUTPUT") ‘ 


This example shows a line from a command procedure that (1) uses the 
F$TRNLNM function to determine the name of the current output device and 
(2) creates a group logical name table entry based on the equivalence string. 


You must enclose the argument SYS$OUTPUT in quotation marks because it 
is a character string. 


Also, in this example you must enclose the F$STRNLNM function in single 
quotation marks to force the lexical function to be evaluated. Otherwise, the 
DEFINE command does not automatically evaluate the lexical function. 


$ RESULT= - 
_$ FSTRNLNM("INFILE","LNMS$PROCESS" ,0,"SUPERVISOR", ,"NO_ ALIAS") 
$ SHOW SYMBOL RESULT 

RESULT = "FALSE" 


In this example, the FSTRNLNM function searches the process logical name 
table for the logical name INFILE. The function starts the search by looking 
for the logical name INFILE created in supervisor mode. If no match is found, 
the function looks for INFILE created in executive mode. 


When a match is found, the F$STRNLNM function determines whether the 
name INFILE was created with the NO_ALIAS attribute. In this case, the 
NO_ALIAS attribute is not specified. 


FSTYPE 


Format 
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Returns the data type of a symbol. The string INTEGER is returned if the symbol 
is equated to an integer, or if the symbol is equated to a string whose characters 
form a valid integer. 


The string STRING is returned if the symbol is equated to a character string 
whose characters do not form a valid integer. 


feet 


If the symbol is undefined, a null string ("") is returned. 


F$TYPE(symbol-name) 


Return Value 


Argument 


Examples 


The string INTEGER is returned if the symbol is equated to an integer, or if the 
symbol is equated to a string whose characters form a valid integer. 

If the symbol has been produced by a call to the FSCONTEXT function with a 
context type of PROCESS or by a call to the F$PID function, the string returned 
is PROCESS_CONTEXT. A symbol retains this type until FSCONTEXT is called 
with the symbol and the CANCEL keyword, or until a null string ("") is returned 
by a call to F$PID. | 


Similarly, the return value is the string CLUSTER_SYSTEM_CONTEXT for 
symbols created by the F$CSID function. 


If the symbol is a context symbol, then the return value will be one of the types 
shown in Table DCLI-15. 


Table DCLI-15 Context Symbol Types 


Symbol Type Lexical Creating Symbol 
PROCESS_CONTEXT F$PID or FSCONTEXT (with PROCESS 
context type) 


CLUSTER_SYSTEM_CONTEXT F$CSID 


The string STRING is returned if the symbol is equated to a character string 
whose characters do not form a valid integer or whose type is not a context. 


If the symbol is undefined, a null string is returned. 


symbol-name 
Specifies the name of the symbol to be evaluated. 


1. $ NUM = "52" 
$ TYPE = F$TYPE(NUM) 
$ SHOW SYMBOL TYPE 
TYPE = "INTEGER" 


This example uses the F$TYPE function to determine the data type of the 
symbol NUM. NUM is equated to the character string “52”. Because the 
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characters in the string form a valid integer, the F$TYPE function returns 
the string INTEGER. 


$ NUM = 52 

$ TYPE = FSTYPE(NUM) 

$ SHOW SYMBOL TYPE 
TYPE = "INTEGER" 


In this example, the symbol NUM is equated to the integer 52. The F$TYPE 
function shows that the symbol has an integer data type. 


$ CHAR = "FIVE" 

$ TYPE = F$TYPE(CHAR) 

$ SHOW SYMBOL TYPE 
TYPE = "STRING" 


In this example, the symbol CHAR is equated to the character string FIVE. 
Because the characters in this string do not form a valid integer, the F$STYPE 
function shows that the symbol has a string value. 


FSCONTEXT( "PROCESS", CTX, "USERNAME", "SMITH" ) 
E = FSTYPE(CTX) 

W SYMBOL TYPE 

E = "PROCESS CONTEXT" 

FSCONTEXT( "PROCESS" , CTX, "CANCEL" ) 


TYPE = "" 


In this example, the F$TYPE function returns the string PROCESS_ 
CONTEXT because the symbol has been produced by a call to the 
F$CONTEXT function with a context type of PROCESS. The symbol returns 
this type until FSCONTEXT is called with the symbol and the selection-item 
argument value CANCEL. 


FSUSER 


Format 


Lexical Functions 
FSUSER 


Returns the current user identification code (UIC) in named format as a character 
string. The F$USER function has no arguments, but must be followed by 


parentheses. 


FSUSER() 


Return Value 


Arguments 


Example 


A character string containing the current UIC, including brackets ([ ]). The UIC 
is returned in the format [group-identifier, member-identifier]. 


None. 


$ UIC = FSUSER() 
$ SHOW SYMBOL UIC 
UIC = "[GROUP6, JENNIFER]" 


In this example the F$USER function returns the current user identification code 
and assigns it to the symbol UIC. 
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FSVERIFY 


Format 


Returns an integer value indicating whether the procedure verification setting 
is currently on or off. If used with arguments, the F$VERIFY function can turn 
the procedure and image verification settings on or off. You must include the - 
parentheses after the F$VERIFY function whether or not you specify arguments. 


F$VERIFY([procedure-value] [,image-value]) 


Return Value 


Arguments 


Description 
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The integer 0 if the procedure verification setting is off, or the integer 1 if the 
procedure verification setting is on. 


procedure-value 
Specifies an integer expression with a value of 1 to turn procedure verification on, 
or a value of 0 to turn procedure verification off. 


When procedure verification is on, each DCL command line in the command 
procedure is displayed on the output device. Procedure verification allows you to 
verify that each command is executing correctly. 


If you use the procedure-value argument, the function first returns the current 
procedure verification setting. Then the command interpreter turns the procedure 
verification on or off, as specified by the argument. 


image-value 
Specifies an integer expression with a value of 1 to turn image verification on, or 
a value of 0 to turn image verification off. 


When image verification is on, data lines in the command procedure are displayed 
on the output device. 


The lexical function F$VERIFY returns an integer value indicating whether the 
procedure verification setting is currently on or off. If used with arguments, the 
F$VERIFY function can turn the procedure and image verification settings on or 
off. You must include the pareninescs after the F$VERIFY function whether or 

not you specify arguments. 


Using the F$VERIFY function in command procedures allows you to test the 
current procedure verification setting. For example, a command procedure can 
save the current procedure verification setting before changing it and then later 
restore the setting. In addition, you can construct a procedure that does not 
display (or print) commands, regardless of what the initial state of verification is. 


When you use the F$VERIFY function, you can specify zero, one, or two 
arguments. If you do not specify any arguments, neither of the verification 
settings is changed. If you specify only the procedure-value argument, both 
procedure and image verification are turned on (if the value is 1) or off (if the 
value is 0). 


Examples 
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If you specify both arguments, procedure and image verification are turned on or 
off independently. If you specify the image-value argument alone, only image 
verification is turned on or off. If you specify the image-value argument alone, 
you must precede the argument with a comma (, ). 


You can also use the FSENVIRONMENT function with VERIFY_PROCEDURE 
or VERIFY_IMAGE as the argument. With the FSENVIRONMENT function, you 
can determine either the procedure or image verification setting; the FSVERIFY 
function determines only the procedure verification setting. 


DCL performs the F$VERIFY function even if it appears after a comment 
character, if it is enclosed in single quotation marks (‘’). This is the only 
processing that DCL performs within a comment. 


1. $ SAVE _PROC_VERIFY = FSENVIRONMENT("VERIFY PROCEDURE") 
$ SAVE IMAGE VERIFY = Ey RN OEE ERIE IMAGE" ) 
$ SET NOVERIFY 


$ TEMP = FSVERIFY(SAVE PROC_VERIFY, SAVE_IMAGE VERIFY) 


This example shows an excerpt from a command procedure. The first 
assignment statement assigns the current procedure verification setting to 
the symbol SAVE_PROC_VERIFY. The second assignment statement assigns 
the current image verification setting to the symbol SAVE_IMAGE_VERIFY. 


Then, the SET NOVERIFY command disables procedure and image 
verification. Later, the F$VERIFY function resets the verification settings, 
using the original values (equated to the symbols SAVE_PROC_VERIFY 
and SAVE_IMAGE_VERIFY). The symbol TEMP contains the procedure 
verification before it is changed with the F$VERIFY function. (In this 
example the value of TEMP is not used.) 


‘2. § VERIFY = FSVERIFY(0) 


$ IF VERIFY .EQ. 1 THEN SET VERIFY 


This example shows an excerpt from a command procedure that uses the 
F$VERIFY function to save the current procedure verification setting and to 
turn both procedure and image verification off. At the end of the command 
procedure, if procedure verification was originally on, both the procedure and 
image verification are turned on. 
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LIBRARY 


Invokes the Librarian utility, which creates, modifies, or describes an object, 

macro, help, text, or shareable image library. For a complete description of the 

Librarian utility, see the OpenVMS Command Definition, Librarian, and Message | 

Utilities Manual. 
Format 


LIBRARY _library-filespec [input-filespecf,...]] 
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LICENSE 
Invokes the License Management utility, which manages software licenses on 
the OpenVMS operating system. For a complete description of the License 
Management utility, see the OpenVMS License Management Utility Manual. 
Format 


LICENSE subcommand parameter 
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LINK 


LINK 
Invokes the OpenVMS Linker, which links one or more object modules into a 
program image and defines execution characteristics of the image. For a complete 
description of the linker, including more information about the LINK command, 
see the OpenVMS Linker Utility Manual. 

Format 


LINK | filespec{,...] 
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LOGIN Procedure 


Format 


Description 


Qualifiers 


Initiates an interactive terminal session. 


There is no LOGIN command. You signal your intention to access the system by 
pressing the Return Key, Ctrl/C, or Ctrl/Y, on a terminal not currently in use. 
The system prompts for your user name and your password (and your secondary 
password, if you have one) and then validates them. 


Specify the optional qualifiers immediately after you type your user name; then 
press the Return key to get the password prompts. 


The login procedure performs the following functions: 


¢ Validates your right to access the system by checking your user name and 
passwords against the entries in the system’s user authorization file (UAF). 


e Establishes the default characteristics of your terminal session based on your 
user name entry in the UAF. 


¢ Executes the command procedure file SYS$SYLOGIN.COM if one exists. 


¢ Executes either the command procedure file named LOGIN.COM if one exists 
in your default directory, or the command file defined in the UAF, if any. 


Some systems are set up with a retry facility for users who are accessing the 
system from remote or dialup locations. With these systems, when you make a 
mistake typing your user name or password, the system allows you to reenter 
the information. To reenter your login information, press the Return key. The 
system displays the user name prompt again. Now retype your user name and 
press the Return key to send the information to the system. The system displays 
the password prompt. (There is both a limit to the number of times you can retry 
to enter your login information and a time limit between tries.) 


/CLi=command-language-interpreter 

Specifies the name of an alternate command language interpreter (CLI) to 
override the default CLI listed in the UAF. The CLI you specify must be located 
in SYS$SYSTEM and have the file type .EXE. 


If you do not specify a command interpreter by using the /CLI qualifier and you 
do not have a default CLI listed in the UAF, the system supplies the qualifier 
/CLI=DCL by default. 


/COMMAND[=filespec] (default) 

/NOCOMMAND 

Controls whether to execute your default login command procedure when you 
log in. Use the /COMMAND qualifier to specify the name of an alternate login 
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Examples 
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command procedure. If you specify a file name without a file type, the default 
file type .COM is used. If you specify the /COMMAND qualifier and omit the file 
specification, your default login command procedure is executed. 


Use the /NOCOMMAND qualifier if you do not want your default login command 
procedure to be executed. 


/DISK=device-name[:] 

Specifies the name of a disk device to be associated with the logical device 
SYS$DISK for the terminal session. This specification overrides the default 
SYS$DISK device established in the UAF. 


/NEW_PASSWORD 

Requires that you change the account password before logging in (as if the 
password had expired). Use this qualifier as a shortcut if you had intended to 
change your password after login, or if you suspect that your password has been 
detected. 


/TABLES=(commanc-table[,...]) 

/TABLES=DCLTABLES (default) 

Specifies the name of an alternate CLI table to override the default listed in the 
UAF. This table name is considered a file specification. The default device and 
directory is SYS$SHARE and the default file type is EXE. 


If a logical name is used, the table name specification must be defined in the 
system logical name table. 


If the /CLI qualifier is set to DCL or MCR, the /TABLES qualifier defaults to the 
correct value. If the /T[ABLES qualifier is specified without the /CLI qualifier, the 
CLI specified in the user’s UAF will be used. 


1. 
Username: SMITHSON 
Password: <PASSWORD> 


In this example, pressing Ctrl/Y allows you to access the operating system, 
which immediately prompts for a user name. After validating the user name, 
the system prompts for the password but does not echo it. 


2. 
Username: HIGGINS/DISK=USER$ 
Password: <PASSWORD> 
Welcome to OpenVMS Alpha (TM) Operating systeni Version 6.2 on node LSR3 
Last interactive login on Tuesday, 18-DEC-1995 08:41 
Last non-interactive login on Monday, 19-DEC-1995 15:43 


In this Alpha example, the /DISK qualifier requests that the default disk for 
the terminal session be USER$. The SHOW DEFAULT command shows that 
USER$ is the default disk. 


LOGIN Procedure 


Username: HIGGINS/DISK=USERS 
Password: <PASSWORD> 
Welcome to OpenVMS VAX Version 6.2 on node JUPITER 
Last interactive login on Tuesday, 15-DEC-1995 09:16:47.08 
Last non-interactive login on Monday, 14-DEC-1995 17:32:34.27 
$ SHOW DEFAULT 
USERS : [HIGGINS ] 


In this VAX example, the /DISK qualifier requests that the default disk for 
the terminal session be USER$. The SHOW DEFAULT command shows that 
USER$ is the default disk. 


ea) 
Username: LIZA/CLI=MCR/COMMAND=ALTLOGIN.COM 
Password: <PASSWORD> 
Welcome to OpenVMS VAX Version 6.2 on node JUPITER 
Last interactive login on Tuesday, 15-DEC-1995 09:16:47.08 
Last non-interactive login on Monday, 14-DEC-1995 17:32:34.27 
> 


In this example, the /CLI qualifier requests the alternate MCR command 
interpreter. The /COMMAND qualifier indicates that the login command file 
ALTLOGIN.COM is to be executed instead of the default login command file. 


The right angle-bracket prompt (>) indicates that MCR is active and expects 
an MCR command. 


Username: XENAKIS 

Password: <PASSWORD> 

Password: <PASSWORD> 
Welcome to OpenVMS VAX Version 6.2 on node JUPITER 
Last interactive login on Tuesday, 15-DEC-1995 09:16:47.08 
Last non-interactive login on Monday, 14-DEC-1995 17:32:34.27 


In this example, the second password prompt indicates that the user has a 
secondary password, which must be entered to access the system. 


Username: JONES 


Password: <PASSWORD> 

User authorization failure 

| 

Username: JONES 

Password: <PASSWORD> 

Welcome to OpenVMS Alpha (TM) Operating System, Version 6.2 on node LSR3 
Last interactive login on Tuesday, 15-DEC-1995 09:16:47.08 

Last non-interactive login on Monday, 14-DEC-1995 17:32:34.27 

1 failure since last successful login. 


$ 


This example shows the “User authorization failure” message, which indicates 
that the password has been entered incorrectly. After you successfully log 

in, a message is displayed showing the number of login failures since your 
last successful login. This message is displayed only if login failures have 
occurred. 
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7. 


Username: JOYCE 

Password: <PASSWORD> 

Welcome to OpenVMS Alpha (TM) Operating System, Version 6.2 on node LSR3 
Last interactive login on Tuesday, 15-DEC-1995 09:16:47.08 
Last non-interactive login on Monday, 14-DEC-1995 17:32:34.27 
WARNING - Primary password has expired; update immediately. 


$ 


This example shows the WARNING message, which indicates that your 
primary password has expired. You must use the SET PASSWORD command 
to change your password before logging out, or you will be unable to log in 
again. 


For more information on changing your password, see the description of the 


SET PASSWORD command in this manual. 


Username: MIHALY/NEW PASSWORD 
Password: <PASSWORD>~ 
Password: <PASSWORD> 
Welcome to OpenVMS VAX Version 6.2 on node JUPITER 
Last interactive login on Tuesday, 15-DEC-1995 09:16:47.08 
Last non-interactive login on Monday, 14-DEC-1995 17:32:34.27 
Your password has expired; you must set a new password to log in. 


Old password: <PASSWORD> 
New password: <PASSWORD> 
Verification: <PASSWORD> 


In this example, the user enters the /NEW_PASSWORD qualifer after the 
user name MIHALY. The system then forces the user to set a new password 
immediately after login. The prompts are the same as those provided when 
you enter the DCL command SET PASSWORD from the command line. 


LOGOUT 


Format 


Description 


Qualifiers 


Examples 


LOGOUT 


Terminates an interactive terminal session. 
LOGOUT 


You must use the LOGOUT command to end a terminal session. Under most 
circumstances, if you turn the power off at your terminal or hang up your 
telephone connection without using the LOGOUT command, you remain logged 
in. 


When you use the SET HOST command to log in to a remote processor, you 
generally need to use the LOGOUT command to end the remote session. 


/BRIEF 
Prints a brief logout message (process name, date, and time) or a full logout 
message (a brief message plus accounting statistics). 


/FULL 

Requests the long form of the logout message. When you specify the /FULL 
qualifier, the command interpreter displays a summary of accounting information 
for the terminal session. The default qualifier for a batch job is /FULi. 


/HANGUP 

/INOHANGUP 

Determines, for dialup terminals, whether the phone hangs up whenever you 
log out. By default, the setting of the /HANGUP qualifier for your terminal port 
determines whether the line is disconnected. Your system manager determines 
whether you are permitted to use this qualifier. 


1. $ LOGOUT 
HIGGINS logged out at 14-DEC-1994 17:48:56.73 


In this example, the LOGOUT command uses the default brief message form. 
No accounting information is displayed. 


2. $ LOGOUT/FULL 
HIGGINS logged out at 14-DEC-1994 14:23:45.30 
Accounting information: 


Buffered I/O count: 22 Peak working set size: 90 
Direct I/O count: 10 Peak virtual size: 69 
Page faults: 68 Mounted volumes: 0 
Charged CPU time: 0 00:01:30.50 Elapsed time: 0 04:59:02.63 


Charged vector CPU time: 0 00:00:21.62 


In this example, the LOGOUT command with the /FULL qualifier displays a 
summary of accounting statistics for the terminal session. 


DCLI-419 


MACRO 


MACRO 


Format 


Parameter 


Description 
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Invokes the VAX MACRO assembler to assemble one or more assembly language 
source files (the default on VAX) or invokes the MACRO-32 compiler for OpenVMS 
Alpha to compile VAX assembly language source files on Alpha (the default on 
Alpha). 


The /ALPHA qualifier causes the MACRO command to invoke the MACRO-64 
assembler if it is installed on Alpha. 


The /MIGRATION qualifier causes the MACRO command to invoke the compiler 
on Alpha. 


MACRO filespecf{,...] 


filespecf{,...] 

Specifies a VAX MACRO assembly language source file to be assembled. If you 
specify more than one file, separate the file specifications with either commas (, ) 
or plus signs (+). File specifications separated by commas cause the MACRO 
assembler to produce an object file (and, if indicated, a listing file) for each 
specified file. File specifications separated by plus signs are concatenated into one 
input file and produce a single object file (and listing file). 


You cannot include the asterisk (*) and the percent sign (% ) wildcard characters 
in a file specification. For each file specification, the MACRO command supplies a 
default file type .MAR. The MACRO assembler creates output files of one version 
higher than the highest version existing in the target directory. 


The MACRO command invokes the VAX MACRO assembler to assemble one or 
more assembly language source files. 


The qualifiers to the MACRO command serve as either command (global) 
qualifiers or positional qualifiers. A command qualifier affects all the files 
specified in the MACRO command. A positional qualifier affects only the file 
that it qualifies. All MACRO qualifiers except the (LIBRARY and /UPDATE 
qualifiers are usable as either command or positional qualifiers. The /LIBRARY 
and /UPDATE qualifiers are positional qualifiers only. 


See the qualifier descriptions for restrictions. 


For a complete functional description of the VAX MACRO assembler directives, 
see the VAX MACRO and Instruction Set Reference Manual. For a complete 
functional description of the MACRO-32 compiler for OpenVMS Alpha, see 
Migrating to an OpenVMS AXP System: Porting VAX MACRO Code. 


Qualifiers 


MACRO 


/ALPHA 

On Alpha, invokes the MACRO-64 assembler for OpenVMS Alpha (if installed on 
the system). For a description of the assembler, see the MACRO-64 Assembler for 
OpenVMS AXP Systems Reference Manual.¢ 


/ANALYSIS_DATA[=filespec] 

/NOANALYSIS_DATA (default) 

Controls whether the assembler creates an analysis data file for the OpenVMS 
Source Code Analyzer (SCA), and optionally provides the file specification. 


By default, the assembler does not create an analysis data file. If you specify the 
/ANALYSIS_DATA qualifier without a file specification, the assembler creates a 
file with the same file name as the first input file for the MACRO command. The 
default file type for analysis data files is .ANA. When you specify the /ANALYSIS_ 
DATA qualifier, you can control the defaults applied to the output file specification 
by the placement of the qualifier in the command line. 


/CROSS_REFERENCE[=(function{,...])] 

/NOCROSS_REFERENCE (default) 

Controls. whether a listing is produced of the locations in the source file where the 
specified function (or functions) is defined or referenced. If you specify only one 
function, you can omit the parentheses. 


You can specify the following functions: 


ALL Cross-references directives, macros, operation codes, 
registers, and symbols 

DIRECTIVES Cross-references directives 

MACROS Cross-references macros 

OPCODES Cross-references operation codes 

REGISTERS Cross-references registers 

SYMBOLS Cross-references symbols 


Because the assembler writes the cross-references to the listing file, you must 
specify the /LIST qualifier with the /CROSS_REFERENCE qualifier. If you 
specify no functions in the /CROSS_REFERENCE qualifier, the assembler 
assumes the default value of /CROSS_REFERENCE=(MACROS,SYMBOLS). The 
/NOCROSS_REFERENCE qualifier excludes the cross-reference listing. 


/DEBUG[=option] 

/NODEBUG (default) 

Includes or excludes local symbols in the symbol table or traceback information in 
the object module. You can replace the /ENABLE and /DISABLE qualifiers with 
the /DEBUG and /NODEBUG qualifiers when you use the appropriate DEBUG 
and TRACEBACK options. The /DEBUG or the /NODEBUG qualifier overrides 
debugging characteristics set with the ENABLE or .DISABLE assembler 


_ directives. 
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You can specify one or more of the following options: 


ALL Includes in the object module all local symbols in the 
symbol table, and provides all traceback information 
for the debugger. This option is equivalent to 
/ENABLE=(DEBUG,TRACEBACK). 

NONE Makes local symbols and traceback information in the 


object module unavailable to the debugger. This option is 
equivalent to /DISABLE=(DEBUG, TRACEBACK). 


SYMBOLS Makes all local symbols in the object module available to the 
debugger. Makes traceback information unavailable to the 
debugger. This option is equivalent to /ENABLE=DEBUG 
and /DISABLE=TRACEBACK together. 

TRACEBACK Makes traceback information in the object module 

. available to the debugger and local symbols unavailable 


to the debugger. This option is equivalent to 
/ENABLE=TRACEBACK and /DISABLE=DEBUG together. 


If you specify no options to the (DEBUG qualifier, it assumes the default value of 
/DEBUG=ALL. 


/DIAGNOSTICS[=filespec] 

/NODIAGNOSTICS (default) 

Creates a file containing assembler messages and diagnostic information. If 
you omit the file specification, the default file name is the same as the source 
program; the default file type is DIA. 


The asterisk (*) and the percent sign (%) wildcard characters are not allowed in 
the file specification. 


The diagnostics file is reserved for use with Digital layered products, such as the 
VAX Language-Sensitive Editor (LSE). 


/DISABLE=(function[,...]) 

/NODISABLE 

Provides initial settings for the functions disabled by the .DISABLE assembler 
directive. You can specify one or more of the following functions: 


ABSOLUTE Assembles relative addresses as absolute addresses. 

DEBUG Includes local symbol table information in the object file for 
use with the debugger. 

GLOBAL Assumes undefined symbols to be external symbols. 

SUPPRESSION Suppresses listing of unreferenced symbols in the symbol 
table. 

TRACEBACK Provides traceback information to the debugger. 

TRUNCATION Truncates floating-point numbers (if truncation is disabled, 
numbers are rounded). 


VECTOR Enables the assembler to accept and correctly process vector 
code. 


If you specify only one function, you can omit the parentheses. If you specify 

no functions in the /DISABLE qualifier, it assumes the default value of 
/DISABLE=(ABSOLUTE,DEBUG, TRUNCATION, VECTOR). The /NODISABLE 
qualifier has the same effect as not specifying the /DISABLE qualifier, or negates 
the effects of any /DISABLE qualifiers specified earlier in the command line. 


MACRO 


/ENABLE=(function],...]) 

/NOENABLE 
Provides initial settings for the functions controlled by the .ENABLE assembler 
directive. You can specify one or more of the following functions: 


ABSOLUTE Assembles relative addresses as absolute addresses. 

DEBUG Includes local symbol table information in the object file for 
use with the debugger. 

GLOBAL Assumes undefined symbols to be external symbols. 

SUPPRESSION Suppresses listing of unreferenced symbols in the symbol 
table. 

TRACEBACK Provides traceback information to the debugger. 


TRUNCATION Truncates floating-point numbers (if truncation is disabled, © 
numbers are rounded). 


VECTOR Enables the assembler to accept and correctly process vector 
code. 


The /NOENABLE qualifier has the same effect as not specifying the 
/ENABLE qualifier, or negates the effects of any /ENABLE qualifiers 
specified earlier in the command line. You can specify one or more of 
the functions listed in the description of the /DISABLE qualifier. If you 
specify only one function, you can omit the parentheses. If you specify 
no functions in the /DISABLE qualifier, it assumes the default value of 
/ENABLE=(GLOBAL,TRACEBACK,SUPPRESSION). 


/LIBRARY 

/NOLIBRARY 

Positional qualifier. The /LIBRARY qualifier cannot be used with the 
/UPDATE qualifier. 


The associated input file to the /LIBRARY qualifier must be a macro library. 
The default file type is MLB. The /NOLIBRARY qualifier has the same effect as 
not specifying the /LIBRARY qualifier, or negates the effects of any /LIBRARY 
qualifiers specified earlier in the command line. 


The assembler can search up to 16 libraries, one of which is always 
STARLET.MLB. This number applies to a particular assembly, not necessarily to 
a particular MACRO command. If you enter the MACRO command so that more 
than one source file is assembled, but the source files are assembled separately, 
you can specify up to 16 macro libraries for each separate assembly. More than 
one macro library in an assembly causes the libraries to be searched in reverse 
order of their specification. 


A macro call in a source program causes the assembler to begin the following 
sequence of searches: 


1. An initial search of the libraries specified with the .LIBRARY directive. The 
assembler searches these libraries in the reverse order of that in which they 
were declared. 


2. Ifthe macro definition is not found in any of the libraries specified with 
the .LIBRARY directive, a search of the libraries specified in the MACRO 
command line (in the reverse order in which they were specified). 


3. Ifthe macro definition is not found in any of the libraries specified in the 
command line, a search of STARLET.MLB. 
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/LIST[=filespec] 

/NOLIST 

Creates or omits an output listing, and optionally provides an output file 
specification for it. The default file type for the listing file is LIS. The asterisk 
(*) and the percent sign (%) wildcard characters are not allowed in the file 
specification. 


An interactive MACRO command does not produce a listing file by default. The 
/NOLIST qualifier, present either explicitly or by default, causes errors to be 
reported on the current output device. 


The /LIST qualifier is the default for a MACRO command in a batch job. The 
/LIST qualifier allows you to control the defaults applied to the output file 
specification by the placement of the qualifier in the command line. For more 
information on entering output file qualifiers, see the OpenVMS User’s Manual. 


/MIGRATION 

On Alpha, invokes the MACRO-32 compiler for OpenVMS Alpha to compile one 
or more VAX MACRO assembly language source files into native OpenVMS Alpha 
object code. 


For a complete description of the MACRO-32 compiler for OpenVMS Alpha, see 
Migrating to an OpenVMS AXP System: Porting VAX MACRO Code.¢ 


On VAX, if the Alpha Migration Service Package is installed on the system, 
invokes the MACRO-32 cross-compiler. The /MIGRATION qualifier is required. 
For more information about the Alpha Migration Service Package, see OpenVMS 
Compatibility Between VAX and Alpha.¢ 


/OBJECT[=filespec] — 

/INOOBJECT 

Creates or omits an object module. It also defines the file specification. By 
default, the assembler creates an object module with the same file name as the 
first input file. The default file type for object files is OBJ. The asterisk (*) and 


- the percent sign (%) wildcard characters are not allowed in the file specification. 


The /OBJECT qualifier controls the defaults applied to the output file specification 
by the placement of the qualifier in the command line. For more information on 
entering output file qualifiers, see the OpenVMS User’s Manual. 


/PREPROCESS_ONLY[=filespec] 

/NOPREPROCESS (D) 

Causes the assembler to perform only the actions of the preprocessor phase and 
writes the resulting processed text out to a file. 


The filespec defaults to the name of the primary source file. The default file type 
is ASM. 


/SHOW[=(function{....])] 

/NOSHOW[=(function{....])] 

Provides initial settings for the functions controlled by the assembler directives 
SHOW and .NOSHOW. 


You can specify one or more of the following functions: 


CONDITIONALS Lists unsatisfied conditional code associated with .IF and 
-ENDC MACRO directives. 


Examples 


MACRO 


CALLS Lists macro calls and repeat range expansions. 

DEFINITIONS Lists macro definitions. 

EXPANSIONS Lists macro expansions. 

BINARY Lists binary code generated by the expansion of macro 
calls. 


If you specify more than one function, separate each with a comma and enclose 
the list in parentheses. If you specify no functions in the /SHOW qualifier, 

it increments the listing level count; the /NOSHOW qualifier decrements the 
count in similar circumstances. Because these qualifiers contribute to the listing 
file, you must also specify the /LIST qualifier when you use them. If you do 

not specify the /SHOW qualifier, the MACRO command assumes a default of 
/SHOW=(CONDITIONALS,CALLS,DEFINITIONS). If you specify only one 
function, you can omit the parentheses. 


/UPDATE[=(update-filespec],...])] 

/NOUPDATE 

Positional qualifier. The /UPDATE qualifier cannot be used with the 
/LIBRARY qualifier. 


Updates the input file it qualifies by using the SUMSLP batch editor and the 
specified update file or files. By default, the assembler assumes that the update 
file has the same file name as the input source file and a file type of UPD. You 
cannot include the asterisk (*) and the percent sign (%) wildcard characters 
in the file specifications. If it cannot find a specified update file, the assembler 
prints an informational message and continues the assembly. 


If you specify only one update file, you can omit the parentheses. If you specify 
more than one update file, the assembler merges the contents into a single list of 
updates before applying the updates to the source file. 


The /NOUPDATE qualifier has the same effect as not specifying the /UPDATE 
qualifier, or negates any /UPDATE qualifiers specified earlier in the command 
line. The input source file and update files are not changed by the update 
operation. The effects of the update appear in the compiled output. If you specify 
the /LIST qualifier with the /UPDATE qualifier, the assembler writes an audit 
trail of the changes to the listing file. 


1. $ MACRO/LIST CYGNUS, LYRA/OBJECT=LYRAN + MYLIB/LIBRARY 


In this example, the MACRO command requests two separate assemblies. 
Using MAR as the default file type, MACRO assembles CYGNUS.MAR to 
produce CYGNUS.LIS and CYGNUS.OBJ. Then it assembles LYRA.MAR 
and creates a listing file named LYRA.LIS and an object module named 
LYRAN.OBJ. The default output file type for a listing is LIS. 


The command requests the search of the MYLIB library file in the current 
directory for macro definitions. 
2. $ MACRO ORION 


MACRO assembles the file ORION.MAR and creates an object file named 
ORION.OBJ. Executing the command in a batch job causes MACRO to create 
a listing file named ORION.LIS. 
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3. 


$ MACRO ALPHA/LIST+MYLIB/LIBRARY- 
$ + [TEST]OLDLIB/LIBRARY + []BETA 
$ PRINT ALPHA 


MACRO concatenates the files ALPHA.MAR and BETA.MAR to produce an 
object file named ALPHA.OBJ and a listing file named ALPHA.LIS. The 
command line requests the search of libraries MYLIB.MLB (in the current 
default directory) and OLDLIB.MLB (in the directory [TEST]) for macro 
definitions. When macro calls are found in BETA.MAR, MACRO searches the 
libraries OLDLIB, MYLIB, and the system Hbrary STARLET.MLB, in that 
order, for the definitions. 


The PRINT command prints the listing file ALPHA.LIS. 


$ MACRO DELTA+TESTLIB/LIBRARY, ALPHA+MYLIB/LIBRARY 


MACRO requests two separate assemblies. MACRO searches TESTLIB.MLB 
and the system library STARLET.MLB for macro definitions when macro 
calls are found in DELTA.MAR, and searches MYLIB.MLB and the system 
library STARLET.MLB for macro definitions when macro calls are found in 
ALPHA.MAR. 


MACRO/MIGRATION (Alpha only) 


MACRO/MIGRATION (Alpha only) 


On Alpha, invokes the MACRO-32 compiler to compile one or more VAX MACRO 
assembly language source files into native Alpha system object code. The 
/MIGRATION qualifier is required. For a complete description of the MACRO- 
32 compiler for OpenVMS Alpha, see Migrating to an OpenVMS AXP System: 
Porting VAX MACRO Code. 





Format 


MACRO/MIGRATION filespecy,...] ¢ 
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MAIL 


MAIL 
Invokes the Mail utility, which is used to send messages to other users of the 
system. For a complete description of the Mail utility, see the OpenVMS User’s 
Manual. 

Format 


MAIL  [filespec] [recipient-name] 
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MERGE 
Invokes the Sort/Merge utility, which combines 2 to 10 similarly sorted input 
files and creates a single output file. Note that input files to be merged must 
be in sorted order. For a complete description of the Sort/Merge utility, see the 
OpenVMS User’s Manual. 

Format 


MERGE _input-filespec1,input-filespec2[,...] output-filespec 
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MESSAGE 


Invokes the Message utility, which compiles one or more files of message 
definitions. For a complete description of the Message utility, see the OpenVMS 
Command Definition, Librarian, and Message Utilities Manual. 


Format 
MESSAGE filespecf,...] 
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Format 


MONITOR 


Invokes the Monitor utility, which monitors classes of systemwide performance 
data at a specified interval. For a complete description of the Monitor utility, see 
the OpenVMS System Management Utilities Reference Manual. 


MONITOR _ [/qualifier[,...J] classnamef{,...] [/qualifierf,...]] 


DCLI-431 


MOUNT 


MOUNT 
Invokes the Mount utility, which makes a disk or magnetic tape volume available 
for processing. For a complete description of the Mount utility, see the OpenVMS 
System Management Utilities Reference Manual. 

Format 


MOUNT device-name[:][,...] [volume-labell,...]] [logical-name[:]] 
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A 


Access control list editor 
See ACL editor 
Accounting 
of detached processes, DCL N-Z, DCLII-—60 
of terminal session, DCL N-Z, DCLII-311 
ACCOUNTING command, DCL A-M, DCLI-14 
See also SET ACCOUNTING command 
ACL editor, DCL A-M, DCLI-196; DCL N-Z, 
DCLIT—200 
Activating an autostart queue, DCL A-M, 
DCLI-207, DCLI-266; DCL N-Z, DCLII-3872 
ALLOCATE command, DCL A-M, DCLI-15 to 
DCLI-17 
See also DISMOUNT command 
See also DEASSIGN command, DCL A-M, 
DCLI-111 
Allocating devices, DCL A-M, DCLI-15 
ANALYZE/AUDIT command, DCL A-M, DCLI-18 
Analyze/Disk_Structure utility, DCL A-M, 
DCLI-20 
ANALYZE/ERROR_LOG command, DCL A-M, 
DCLI-21 
ANALYZE/IMAGE command, DCL A-M, DCLI-22 
to DCLI-24 
ANALYZE/MEDIA command, DCL A-M, DCLI-25 
ANALYZE/OBJECT command, DCL A-M,,. 
DCLI-26 to DCLI-29 
ANALYZE/PROCESS_DUMP command, DCL 
A-M, DCLI-30 to DCLI-33 
ANALYZE/RMS_FILE command, DCL A-M, 
DCLI-34 
ANALYZE/SYSTEM command, DCL A-M, 
DCLI-35 
Analyzing 
dump files, DCL A-M, DCLI-30 
global symbol tables, DCL A-M, DCLI-—23 
image file, DCL A-M, DCLI-22 
image file fixup section, DCL A-M, DCLI-23 
image file patch text records, DCL A-M, 
DCLI-24 
object files, DCL A-M, DCLI-26 to DCLI-29 
debugger information records, DCL A-M, 
DCLI-27 | 
end-of-module records, DCL A-M, DCLI-27 
global symbol directory records, DCL A-M, 
DCLI-28 


index 


Analyzing 
object files (cont'd) 
link option specification records, DCL A-M, 
DCLI-28 
module header records, DCL A-M, 
DCLI-28 
module traceback records, DCL A-M, 
DCLI-28 
relocation records, DCL A-M, DCLI-29 
text, DCL A-M, DCLI-29 
object module, DCL A-M, DCLI-26 
output converter, DCL A-M, DCLI-67 
processing options, DCL A-M, DCLI-71 
patch text record, DCL A-M, DCLI—24 
restrictions, DCL A-M, DCLI-—30 
shareable image file, DCL A-M, DCLI-22 
APPEND command, DCL A-M, DCLI-36 to 
DCLI-+40 
See also COPY command 
using with DECwindows compound documents, 
DCL A-M, DCLI-386 
Applications 
running locally, DCL N-Z, DCLII-119 
' running remotely, DCL N-Z, DCLII-119 
ASSIGN command, DCL A-M, DCLI-—41 to 
DCLI-46 
See also DEASSIGN command 
Assigning 
logical queue to an execution queue, DCL A-M, 
DCLI-48 
queue name, DCL A-M, DCLI-263 
queue options, DCL A-M, DCLI-263; DCL 
N-Z, DCLII-872 
symbols interactively, DCL A-M, DCLI-278 
= (Assignment statement) command, DCL A-M, 
DCLI-1 to DCLI-—4 
ASSIGN/MERGE command, DCL A-M, DCLI-47 
ASSIGN/QUEUE command, DCL A-M, DCLI-48, 
DCLI-49 
See also DEASSIGN/QUEUE command 
ASTs (asynchronous system traps) 
specifying quota, DCL N-Z, DCLII-61 
Asynchronous system traps 


See ASTs 
ATTACH command, DCL A-M, DCLI-50, 
DCLI-51 
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Automatic unshelving 
controlling, DCL N-Z, DCLII-—177 
determining, DCL A-M, DCLI-346; DCL N-Z, 
DCLII-313 
Autostart queues, DCL A-M, DCLI-266; DCL 
N-Z, DCLII-372 to DCLII-373 
activating, DCL A-M, DCLI-207, DCLI-266; 
DCL N-Z, DCLII-372, DCLII~373 
creating, DCL A-M, DCLI-266 
deactivating, DCL N-Z, DCLIT—400, DCLII—404 
designating, DCL A-M, DCLI-265; DCL N-Z, 
DCLII-373 
disabling, DCL A-M, DCLI-180; DCL N-Z, 
DCLII-406 . 
enabling on a node, DCL A-M, DCLI-207 
failover, DCL A-M, DCLI-180, DCLI-207 
preparing for a shutdown, DCL N-Z, 
DCLII-407 ~ 
preventing failover, DCL A-M, DCLI-180 
restarting after deactivating, DCL N-Z, 
DCLII—400, DCLIT—404 
starting, DCL A-M, DCLI-266; DCL N-Z, 
DCLII-372 
stopping before shutdown, DCL A-M, 
DCLI-180 . 
Availability of queues, DCL A-M, DCLI-266; 
DCL N-Z, DCLII-373 


B 


BACKUP command, DCL A-M, DCLI-52 
Bad block data 
on disks, DCL A-M, DCLI-261 
Base priority 
establishing for batch jobs, DCL A-M, 
DCLI-266; DCL N-Z, DCLH-183 
Batch jobs 
defining default working sets, DCL A-M, 
DCLI-275, DCLI-285; DCL N-Z, 
DCLII-188, DCLII-381, DCLIH-418 
defining maximum CPU time limit, DCL A-M, 
DCLI-283 
defining working set extent, DCL A-M, 
DCLI-275, DCLI-285; DCL N-Z, 
DCLII-188, DCLII-381, DCLIT-—419 
defining working set quotas, DCL A-M, 
DCLI-285; DCL N-Z, DCLII-189, 
DCLI-381, DCLII-419 
deleting files 
after processing, DCL N-Z, DCLII-413 
deleting log files, DCL A-M, DCLI-283; DCL 
N-Z, DCLII-414 
end of job on cards, DCL A-M, DCLI-213 
flushing output buffers, DCL N-Z, DCLII—168 
holding, DCL A-M, DCLI-283; DCL N-Z, 
DCLII-414 
keeping log files, DCL N-Z, DCLII—414 
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Batch jobs (cont’d) 
limiting CPU time of, DCL A-M, DCLI-283; 
DCL N-Z, DCLII—414 
log files, DCL N-Z, DCLIT—410 
on remote network node, DCL N-Z, DCLII-416 
passing parameters to, DCL N-Z, DCLII-415 
password, DCL N-Z, DCLII-—10 
priority, DCL N-Z, DCLII-416 
saving log file). DCL A-M, DCLI-283 
stopping process, DCL N-Z, DCLII-389 
submitting through cards, DCL A-M, 
DCLI-282 
synchronizing with process, DCL N-Z, 
DCLII-422 
working set 
defining default, DCL A-M, DCLI-275, 
DCLI-285; DCL N-Z, DCLII—188, 
DCLII-381, DCLII-418 
defining extent for, DCL A-M, DCLI-275, 
DCLI-285; DCL N-Z, DCLII-188, 
DCLII-381, DCLII-419 
defining quotas for, DCL A-M, DCLI-285; 
DCL N-Z, DCLIJ-189, DCLII-381, 
DCLII-419 
Batch-oriented editor, DCL A-M, DCLI-202 
Batch queues 
See Queues 
Block size options 
for files, DCL A-M, DCLI-176 
specifying cluster size on disk, DCL A-M, 
DCLI-255 
Byte dumps, DCL A-M, DCLI-189 


C 


CALL command, DCL A-M, DCLI-53 to DCLI-56 
CANCEL command, DCL A-M, DCLI-57 to 
DCLI-58 
Canceling 
logical name assignments, DCL A-M, 
DCLI-111 
of detached process wakeup request, DCL N-Z, 
DCLIT-60 
of subprocess wakeup requests, DCL N-Z, 
DCLII-60 
Card readers 
end of batch job, DCL A-M, DCLI-213 
Cards 
submitting batch job on, DCL A-M, DCLI-282 
CDU 
invoking, DCL N-Z, DCLII—101 
Central processing units 
See CPUs 
Changing queue options, DCL N-Z, DCLII-372 
Character strings 
finding in files, DCL N-Z, DCLII-69 
specifying case for search, DCL N-Z, DCLII-69 - 


Character strings (cont'd) 

symbol assignment, DCL A-M, DCLI-5 
CLOSE command, DCL A-M, DCLI-59, DCLI-60 
Command Definition utility (CDU) 


See CDU 
Command interpreters 
controlling error checking of, DCL N-Z, 
DCLII—167 
specifying alternate, DCL A-M, DCLI-415 
Command procedures 
continuing execution of, DCL A-M, DCLI-64 
controlling error checking in, DCL N-Z, 
DCLIT-167 
delaying process of, DCL N-Z, DCLII-433 
displaying command lines of, DCL N-Z, 
DCLITI-—228 
displaying prompts of, DCL A-M, DCLI-278 
executing, DCL A-M, DCLI-9 
labels, DCL A-M, DCLI-53, DCLI-232, 
DCLI-234 
parameters for, DCL A-M, DCLI-9 
passing symbols to interactively, DCL A-M, 
DCLI-278 
resuming execution of, DCL A-M, DCLI-64 
stopping and returning to command level 0, 
DCL N-Z, DCLII-389 
‘submitting as batch jobs, DCL N-Z, DCLII-410 
terminating, DCL A-M, DCLI-227 
testing expressions, DCL A-M, DCLI-250 
transferring control within, DCL A-M, . 
DCLI-53, DCLI-232, DCLI-234 
Command verification 
using SET PREFIX, DCL N-Z, DCLII-172 
Comment characters, DCL A-M, DCLI-160 
See also DIFFERENCES command 
Comment delimiters, DCL A-M, DCLI-160 


See also DIFFERENCES command 
Comparing 
characters in records, DCL A-M, DCLI-158 
files, DCL A-M, DCLI-158 
Concatenating files, DCL A-M, DCLI-36, 
DCLI-79 
CONNECT command, DCL A-M, DCLI-61 to 
DCLI-63 
Continuation 
of interrupted command procedures, DCL A-M, 
DCLI-64 
of interrupted DCL commands, DCL A-M, 
. DCLI-64 . 
of interrupted programs, DCL A-M, DCLI-64 
CONTINUE command, DCL A-M, DCLI-64 
CONVERT command, DCL A-M, DCLI-65 
CONVERT/DOCUMENT command, DCL A-M, 
DCLI-—66 to DCLI-77 
creating an options file, DCL A-M, DCLI-71 


CONVERT/RECLAIM command, DCL A-M, 
DCLI-78 
COPY command, DCL A-M, DCLI-79 to DCLI-88 
using with DECwindows compound documents, 
DCL A-M, DCLI-80 
COPY/FTP command, DCL A-M, DCLI-89 to 
DCLI-90 
qualifiers, DCL A-M, DCLI-89 
Copying directory files, DCL A-M, DCLI-81 
COPY/RCP command, DCL A-M, DCLI-91 to 
DCLI-92__. 
qualifiers, DCL A-M, DCLI-91 
CPUs (central processing units) 
defining maximum time limit for batch jobs, 
DCL A-M, DCLI-268, DCLI-283; DCL 
N-Z, DCLII-184, DCLI-375 
displaying error count for, DCL N-Z, 
DCLII-275 
limiting time for batch jobs, DCL A-M, 
DCLI-268; DCL N-Z, DCLII-123, 
DCLII-184, DCLII-375, DCLII—-413 
time used by current process, DCL N-Z, 
DCLII-339 
CREATE command, DCL A-M, DCLI-98 to 
DCLI-95 
CREATE/DIRECTORY command, DCL A-M, 
DCLI-96 to DCLI-98_ . 
CREATE/FDL command, DCL A-M, DCLI-99 
CREATE/NAME_TABLE command, DCL A-M, 
DCLI-100 to DCLI—103 
CREATE/TERMINAL command, DCL A-M, 
DCLI-104 to DCLI-109 
Creating queues, DCL A-M, DCLI-263 
Ctrl/C key sequence 
enabling or disabling, DCL N-Z, DCLII-104 
Ctrl/O key sequence, DCL N-Z, DCLII—424 
Ctrl/Q key sequence, DCL N-Z, DCLII—424 
Ctrl/S key sequence, DCL N-Z, DCLII-424 
Ctrl/T key sequence 
enabling or disabling, DCL N-Z, DCLII-104 
Ctrl/Y key sequence 
enabling or disabling, DCL N-Z, DCLII-104 


D 


Data checks 
changing default, DCL N-Z, DCLI-231 
Data record compaction, DCL A-M, DCLI-259 
TA90E support, DCL N-Z, DCLII-163 
Data streams 
marking beginning of, DCL A-M, DCLI-117 
marking end of, DCL A-M, DCLI-211 
Days 
setting primary, DCL N-Z, DCLIIJ-106 - 
setting secondary, DCL N-Z, DCLII-106 
DCL commands 
- continuing execution of, DCL A-M, DCLI-64 
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DCL commands (cont'd) 
marking beginning of input stream, DCL A-M, 
DCLI-117 Fe 
marking end of input stream, DCL A-M, 
DCLI-211 
resuming execution of, DCL A-M, DCLI-64 
SET SECURITY, DCL N-Z, DCLII—200 
SHOW AUDIT, DCL N-Z, DCLII-242 
SHOW SECURITY, DCL N-Z, DCLII-335 
DDIF input converter, DCL A-M, DCLI-67 
DDIF output converter, DCL A-M, DCLI-68 
DEALLOCATE command, DCL A-M, DCLI-110 


See also ALLOCATE command 
Deallocating devices, DCL A-M, DCLI-110 
DEASSIGN command, DCL A-M, DCLI-111 to 
DCLI-114 
See also DEFINE command 
DEASSIGN/QUEUE command, DCL A-M, 
DCLI-115 
DEBUG command, DCL A-M, DCLI-116 
Debugger 
analyzing in object files, DCL A-M, DCLI-27 
information record analysis, DCL A-M, 
DCLI-27 
invoking, DCL A-M, DCLI-30, DCLI—116 
Kept Debugger, DCL A-M, DCLI-116 
RUN command, DCL N-Z, DCLITI-56 
using with DEPOSIT command, DCL A-M, 
DCLI-153 
using with EXAMINE command, DCL A-M, 
DCLI-214 
Decimal dump, DCL A-M, DCLI-189 
DECK command, DCL A-M, DCLI-117 to 
DCLI-119 
See also EOD command 
DECnet for OpenVMS, DCL N-Z, DCLII-138, 
DCLIJ-148, DCLIT—150 . 
running DECwindows applications across, DCL 
N-Z, DCLII-119 
DECterm window : 
setting application keypad, DCL A-M, 
DCLI-105 
DEC Text Processing Utility 
See DECTPU 
DECTPU 
invoking, DCL A-M, DCLI-206 
DECWS$DISPLAY logical name, DCL N-Z, 
DCLII-115, DCLII-268 
Default characteristics 
modifying terminal, DCL N-Z, DCLII-213 to 
DCLII-225 
setting for magnetic tape devices, DCL N-Z, 
DCLII-163 
Default devices 
displaying, DCL N-Z, DCLII—254 
Default directories 
displaying, DCL N-Z, DCLII-254 
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Default error checking 
controlling, DCL N-Z, DCLII—-167 
Default printer 
displaying characteristics of, DCL N-Z, 
DCLII-308 
Default protection 
establishing, DCL N-Z, DCLII—182 
Default working set 
for batch jobs, DCL A-M, DCLI-285; DCL 
N-Z, DCLII-188, DCLII-381, DCLII—418 
modifying size, DCL N-Z, DCLII—235 
DEFINE/CHARACTERISTIC command, DCL 
A-M, DCLI-126 to DCLI-127 
DEFINE command, DCL A-M, DCLI-120 to 
DCLI-125 
See also DEASSIGN command 


_ DEFINE/FORM command, DCL A-M, DCLI-128 


to DCLI-131 

DEFINE/KEY command, DCL A-M, DCLI-132 to 
DCLI-135 

Delaying command processing, DCL N-Z, 
DCLI-483 

See also Wait states 

DELETE/CHARACTERISTIC command, DCL 
A-M, DCLI-140 

DELETE command, DCL A-M, DCLI-136 to 
DCLI-139 

DELETE/ENTRY command, DCL A-M, DCLI-141 
to DCLI-143 

DELETE/FORM command, DCL A-M, DCLI-144 

DELETE/INTRUSION_RECORD command, DCL 
A-M, DCLI-145 

DELETE/KEY command, DCL A-M, DCLI-—146 to 
DCLI-147 


DELETE/QUEUE command, DCL A-M, 


DCLI-148 to DCLI-149 
DELETE/QUEUE/MANAGER command, DCL 
A-M, DCLI-150 
DELETE/SYMBOL command, DCL A-M, 
DCLI-151 to DCLI-152 
Deleting 
batch job file after processing, DCL N-Z, 
DCLII-413 
logical names, DCL A-M, DCLI-111 
logical name tables, DCL A-M, DCLI-111 
multiple files, DCL A-M, DCLI-136 
wakeup request, DCL N-Z, DCLII-60 
DEPOSIT command, DCL A-M, DCLI-1583 to 
DCLI-156 
~ See also EXAMINE command 
length qualifiers, DCL A-M, DCLI-154 
radix qualifiers, DCL A-M, DCLI-154 
Descriptor dump, DCL A-M, DCLI-189 
Detached processes 
See also Processes 
creating, DCL N-Z, DCLII-66 
image hibernation, DCL N-Z, DCLII-60 


Detached processes (cont’d) 
specifying working set, DCL N-Z, DCLI-66 
Device driver images 
patching, DCL N-Z, DCLII-12 
Device names 
assigning logical names to, DCL A-M, 
DCLI-41, DCLI-120 
Devices 
access, DCL A-M, DCLI-15 
allocating, DCL A-M, DCLI-15 
assigning logical queue name to, DCL A-M, 
DCLI-48 
creating, DCL N-Z, DCLII-115 
deallocating, DCL A-M, DCLI-110 
dismounting, DCL A-M, DCLI-184 
displaying 
default, DCL N-Z, DCLII-254 
information on, DCL N-Z, DCLII—237 
mounted volumes, DCL N-Z, DCLII—258 
queue entries, DCL N-Z, DCLII-—270, 
DCLIT-319 
status of, DCL N-Z, DCLII—256 
displaying error count for, DCL N-Z, — 
DCLIT—275 
establishing as spooled, DCL N-Z, DCLII—109 
establishing operational status for, DCL N-Z, 
DCLII-109 
logical name assignment, DCL A-M, DCLI-15 
magnetic tapes 
setting default characteristics for, DCL 
N-Z, DCLII-163 
modifying, DCL N-Z, DCLII-—115 
unloading with DISMOUNT command, DCL 
A-M, DCLI-186 
virtual, DCL A-M, DCLI-217, DCLI-339 
DIAGNOSE command, DCL A-M, DCLI-157 
DIFFERENCES command, DCL A-M, DCLI—158 
to DCLI—-167 
comment characters, DCL A-M, DCLI-161 
comment delimiters, DCL A-M, DCLI-160 
exit status, DCL A-M, DCLI-159 
output formats, DCL A-M, DCLI-163 
DIGITAL Standard Runoff 
See DSR 
Directories 
changing specification, DCL N-Z, DCLI-39 
copying, DCL A-M, DCLI-81 
creating, DCL A-M, DCLI-96 
displaying contents of, DCL A-M, DCLI-168 
displaying default, DCL N-Z, DCLII—254 
file version limit 
defining at creation, DCL A-M, DCLI-97 
modifying, DCL N-Z, DCLII-112 
modifying number in system space 
for Files—11 volume, DCL N-Z, DCLII-231 
protection 
defining at creation, DCL A-M, DCLI-97 
ready access, DCL A-M, DCLI-254 


Directories (cont’d) 
shelved files, DCL A-M, DCLI-175 
space preallocation on disk, DCL A-M, 
DCLI-—256 
DIRECTORY command, DCL A-M, DCLI-168 to 
DCLI-179 
DISABLE AUTOSTART command, DCL A-M, 
DCLI-180 to DCLI-181 
Disabling autostart 
on anode, DCL A-M, DCLI-180; DCL N-Z, 
~ DCLI-406 
DISCONNECT command, DCL A-M, DCLI-182 to 
DCLI-183 
Disk quotas 
displaying, DCL N-Z, DCLII-333 
Disks | 
allocating mapping pointers, DCL A-M, 
DCLI-—261 
creating sequential files, DCL A-M, DCLI-93 
defining shareable volume, DCL A-M, 
DCLI-—260 
defining structure level, DCL A-M, DCLI-261 
directory space allocation, DCL A-M, 
DCLI-256 
disabling operator status, DCL N-Z, DCLII-—45 
dismounting, DCL A-M, DCLI-184 
dismounting volume set, DCL A-M, DCLI-186 
displaying quota, DCL N-Z, DCLII-333 
enabling operator status, DCL N-Z, DCLII-45 
establishing operational status for, DCL N-Z, 
DCLII-109 
files 
comparing, DCL A-M, DCLI-158 
deleting, DCL A-M, DCLI-136 
index file placement, DCL A-M, DCLI-258 
indicating bad block data, DCL A-M, DCLI-261 
modifying RMS defaults for file operations, 
DCL N-Z, DCLII—196 
renaming directory, DCL N-Z, DCLII-39 
renaming file, DCL N-Z, DCLII-39 
specifying cluster size, DCL A-M, DCLI-255 
specifying default file extension size, DCL A-M, 
DCLI-—256 
specifying density, DCL A-M, DCLI-255 
specifying faulty areas, DCL A-M, DCLI-254 
specifying maximum file number, DCL A-M, 
DCLI-258 . 
specifying size for DECram disk, DCL A-M, 
DCLI-260 
Disk volumes 
initializing, DCL A-M, DCLI-253 
DISMOUNT command, DCL A-M, DCLI-184 to 
DCLI-187 
Dismounting 
 clusterwide volumes, DCL A-M, DCLI-185 
disks, DCL A-M, DCLI-184 
shared devices, DCL A-M, DCLI-185 
tapes, DCL A-M, DCLI-184 
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Displays 
allocated device, DCL N-Z, DCLII-257 
command procedure, DCL N-Z, DCLII-228 
current process status, DCL N-Z, DCLII-—339 
date, DCL N-Z, DCLII-353 
device status, DCL N-Z, DCLII-—237, 
DCLII-256 
files on current output device, DCL N-Z, 
DCLIT-424 
names of installed files, DCL N-Z, DCLII—257, 
DCLII-260 
names of open files, DCL N-Z, DCLII-257 
process status, DCL N-Z, DCLII-237 
system status, DCL N-Z, DCLII—237 
time, DCL N-Z, DCLII-353 
working set limit or quota, DCL N-Z, 
DCLH-361 
Document conversion 
output formats, DCL A-M, DCLI-66 
Dollar sign ($) 
and DECK command, DCL A-M, DCLI-117 
and EOD command, DCL A-M, DCLI-211 
and EOJ command, DCL A-M, DCLI-213 
Domain converter 
processing options, DCL A-M, DCLI-75 
DSR (DIGITAL Standard Runoff), DCL N-Z, 
_ DCLII-68 
invoking, DCL N-Z, DCLHI-68 
text file formatting, DCL N-Z, DCLII-68 
DTIF input converter, DCL A-M, DCLI-68 
DTIF output converter, DCL A-M, DCLI-69 
DUMP command, DCL A-M, DCLI-—188 to 
DCLI-195 
Dump formats, DCL A-M, DCLI-189 to DCLI-193 
byte, DCL A-M, DCLI-189 
decimal, DCL A-M, DCLI-189 
descriptor, DCL A-M, DCLI-189 
hexadecimal, DCL A-M, DCLI-190 
identifier, DCL A-M, DCLI-190 
longword, DCL A-M, DCLI-190 
octal, DCL A-M, DCLI-191 
word, DCL A-M, DCLI-192 
Dumping 
of files, DCL A-M, DCLI-188 
of volumes, DCL A-M, DCLI-188 
Dump reading, DCL A-M, DCLI-188 
Duplicate labels 
command interpreter rules for, DCL A-M, 
DCLI-53, DCLI-232, DCLI-234 


E 


EDIT/ACL command, DCL A-M, DCLI-196 

EDIT/EDT command, DCL A-M, DCLI-197 to 
DCLI-200 

EDIT/FDL command, DCL A-M, DCLI-201 


Index—6 


Editors 
See EDT editor 
See EVE 
See SUMSLP editor 
See TECO editor 
EDIT/SUM command, DCL A-M, DCLI-202 
EDIT/TECO command, DCL A-M, DCLI-—203 to 
DCLI-205 
EDIT/TPU command, DCL A-M, DCLI-206 
EDT editor, DCL A-M, DCLI-197 
ELSE keyword 
and IF command, DCL A-M, DCLI-250 
ENABLE AUTOSTART command, DCL A-M, 
DCLI-207 to DCLI-209 
Enabling autostart on a node, DCL A-M, 
DCLI-207 
End of batch job on cards, DCL A-M, DCLI-213 
End of data stream, DCL A-M, DCLI-211 
See also EOD command 
End-of-module record analysis, DCL A-M, 
DCLI-27 
ENDSUBROUTINE command, DCL A-M, 
DCLI-54, DCLI-55, DCLI-210 
EOD (end of deck) 
See EOD command 
EOD command, DCL A-M, DCLI-—211, DCLI-212 
and DECK command, DCL A-M, DCLI-117 
EOF condition, DCL A-M, DCLI-211 
EOF indicator, DCL A-M, DCLI-117 
EOJ command, DCL A-M, DCLI-213 
Equivalence names 
assigning to logical names, DCL A-M, 
DCLI-41, DCLI-120 
displaying for logical names, DCL N-Z, 
DCLII-354 
Error messages 
online documentation, DCL A-M, DCLI-244 
Errors 
controlling error checking, DCL N-Z, 
DCLII-167 
reporting 
for image files, DCL A-M, DCLI-22 
for object files, DCL A-M, DCLI-26 
Error streams 
defining for created process, DCL N-Z, 
DCLII-58 
EVE 
invoking, DCL A-M, DCLI-206 
EXAMINE command, DCL A-M, DCLI-214 to 
DCLI-216 
and DEPOSIT command, DCL A-M, DCLI-153 
length qualifier, DCL A-M, DCLI-215 
EXCHANGE command, DCL A-M, DCLI-217 
EXCHANGE/NETWORK command, DCL A-M, 
DCLI-218 to DCLI-226 
creating files, DCL A-M, DCLI-221 
protecting files, DCL A-M, DCLI-221 


EXCHANGE/NETWORK command (cont’d) 
qualifiers, DCL A-M, DCLI-222 
transferring files, DCL A-M, DCLI-—220 
wildcard character, DCL A-M, DCLI-221 

Executable images 
patching, DCL N-Z, DCLII-12 

Execute procedure (@) command, DCL A-M, 

DCLI-9 to DCLI-13 

Executing 

alternate login command procedure, DCL A-M, 
DCLI-415 

continuing interrupted command procedures, 
DCL A-M, DCLI-64 

continuing interrupted programs, DCL A-M, 
DCLI-64 

login command procedure, DCL A-M, 
DCLI-415 

SYS$LOGIN, DCL A-M, DCLI-415 

Execution queues, DCL A-M, DCLI-264 

designating autostart or nonautostart, DCL 
A-M, DCLI-265 

specifying node or node and device, DCL A-M, 
DCLI-266 

/EXECUTIVE_MODE qualifier 
ASSIGN command, DCL A-M, DCLI-42 

EXIT command, DCL A-M, DCLI-227 to 

DCLI-230 
See also STOP command 

Expressions 
value tests, DCL A-M, DCLI-250 

Extensible Versatile Editor 
See EVE 


F 


F$CONTEXT lexical function, DCL A-M, 
DCLI-288, DCLI-291 to DCLI-296 

F$CSID lexical function, DCL A-M, DCLI-288, 
DCLI-297, DCLI-298 

F$CVSI lexical function, DCL A-M, DCLI-289, 
DCLI-299, DCLI-300 

F$CVTIME lexical function, DCL A-M, DCLI-289, 
DCLI-301, DCLI-302 

F$CVUI lexical function, DCL A-M, DCLI-289, 
DCLI-303 

F$DEVICE lexical function, DCL A-M, DCLI-289, 
DCLI-304, DCLI-305 

F$DIRECTORY lexical function, DCL A-M, 
DCLI-289, DCLI-306 

F$EDIT lexical function, DCL A-M, DCLI-289, 
DCLI-307, DCLI-308 

F$ELEMENT lexical function, DCL A-M, 
DCLI-—289, DCLI-309, DCLI-310 

FSENVIRONMENT lexical function, DCL A-M, 
DCLI-289, DCLI-311 to DCLI-313 


F$EXTRACT lexical function, DCL A-M, 
DCLI-289, DCLI-314, DCLI-315 
F$FAO lexical function, DCL A-M, DCLI-289, 
DCLI-316 to DCLI-322 
F$FILE_ATTRIBUTES lexical function, DCL 
A-M, DCLI-289, DCLI-323 to DCLI-325 
F$GETDVI lexical function, DCL A-M, DCLI-289, 
DCLI-326 to DCLI-341 
F$GETJPI lexical function, DCL A-M, DCLI-289, 
DCLI-342 to DCLI-347 
F$GETQUI lexical function, DCL A-M, DCLI-289, 
DCLI-348 to DCLI-370 
F$GETSYI lexical function, DCL A-M, DCLI-289, 
DCLI-371 to DCLI-376 
FSIDENTIFIER lexical function, DCL A-M, 
DCLI-289, DCLI-377, DCLI-378 
F$INTEGER lexical function, DCL A-M, 
DCLI-289, DCLI-379 
F$LENGTH lexical function, DCL A-M, 
DCLI-290, DCLI-380 
F$LOCATE lexical function, DCL A-M, 
DCLI-290, DCLI-381, DCLI-382 
F$LOGICAL lexical function 
See F$TRNLNM lexical function 
FS$MESSAGE lexical function, DCL A-M, 
DCLI-290, DCLI-383, DCLI-384 
F$MODE lexical function, DCL A-M, DCLI-290, 
DCLI-385, DCLI-—386 
F$PARSE lexical function, DCL A-M, DCLI-290, 
DCLI-387 to DCLI-389 . 
F$PID lexical function, DCL A-M, DCLI-290, 
DCLI-390, DCLI-391 
F$PRIVILEGE lexical function, DCL A-M, 
DCLI-290, DCLI-392 
F$PROCESS lexical function, DCL A-M, 
DCLI-290, DCLI-393 
F$SEARCH lexical function, DCL A-M, 
DCLI-290, DCLI-394 to DCLI-396 . 
F$SETPRV lexical function, DCL A-M, DCLI-290, 
DCLI-397 to DCLI—400 
F$STRING lexical function, DCL A-M, DCLI-290, 
DCLI-401 
F$TIME lexical function, DCL A-M, DCLI-290, 
DCLI—402 
F$TRNLNM lexical function, DCL A-M, 
DCLI-290, DCLI-403 to DCLI~406 
F$TYPE lexical function, DCL A-M, DCLI-407, 
DCLI-408 | 
F$USER lexical function, DCL A-M, DCLI-290, 
DCLI—409 
F$VERIFY lexical function, DCL A-M, DCLI-290, 
DCLI-410, DCLI-411 
Failover . 
autostart, DCL A-M, DCLI-276 
autostart queues, DCL A-M, DCLI-180, 
DCLI-207, DCLI-266; DCL N-Z, 
DCLIT-373 
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Failover (cont’d) 
of queue manager, DCL N-Z, DCLII-385 
preventing, DCL A-M, DCLI-180 
False expression 
and IF command, DCL A-M, DCLI-250 
FAO lexical directives, DCL A-M, DCLI-316 to 
DCLI-~322 
FHM (file high-water mark), DCL A-M, DCLI-258 
File expiration date 
specifying retention time values, DCL N-Z, 
DCLII-—233 
File high-water mark 


See FHM 
File images 
analyzing, DCL A-M, DCLI~22 
fixup section analyzing, DCL A-M, DCLI-23 
File names 
changing, DCL N-Z, DCLII-39 
File objects, DCL A-M, DCLI-26 to DCLI-29 
analyzing, DCL A-M, DCLI-26 
debugger information records, DCL A-M, 
DCLI-27 
global symbol directory records, DCL A-M, 
DCLI-28 
link option specification records, DCL A-M, 
DCLI-28 
module header records, DCL A-M, 
DCLI-28 
module traceback records, DCL A-M, 
DCLI-28 
relocation records, DCL A-M, DCLI-29 
text, DCL A-M, DCLI-29 
identifying 
errors, DCL A-M, DCLI~26 
File protection 
changing default for volume, DCL N-Z, 
DCLII-231 
defining at file creation, DCL A-M, DCLI-94 
defining default, DCL A-M, DCLI-—256 
establishing default, DCL N-Z, DCLII-—182 
with EXCHANGE/NETWORK command, DCL 
A-M, DCLI-221 
Files 
allocating headers, DCL A-M, DCLI-257 
appending, DCL A-M, DCLI-36 
batch jobs 
deleting after processing, DCL N-Z, 
DCLII-413 
closing, DCL A-M, DCLI-59 
closing of queue database, DCL N-Z, 
DCLII-399 
comparing, DCL A-M, DCLI-158 
concatenating, DCL A-M, DCLI-79 
copying, DCL A-M, DCLI-79, DCLI-218 
creating, DCL A-M, DCLI-79, DCLI-93, 
DCLI-218 
with EDT editor, DCL A-M, DCLI-197 
with TECO editor, DCL A-M, DCLI-203 
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Files (cont’d) 
creating owner UIC, DCL A-M, DCLI-94 
deassigning logical names, DCL A-M, DCLI-59 
default extension size on disk, DCL A-M, 
DCLI-256 
deleting, DCL A-M, DCLI-136 
displaying 
allocated blocks, DCL A-M, DCLI-176 
at terminal, DCL N-Z, DCLII-424 
backup date, DCL A-M, DCLI-170 
backup time, DCL A-M, DCLI-176 
blocks used, DCL A-M, DCLI-176 
creation date, DCL A-M, DCLI-170 
creation time, DCL A-M, DCLI-176 
expiration date, DCL A-M, DCLI-170 
expiration time, DCL A-M, DCLI-176 
files opened by the system, DCL N-Z, 
DCLII-260 
help, DCL A-M, DCLI-236 
latest version, DCL A-M, DCLI-177 
modification date, DCL A-M, DCLI-170 
modification time, DCL A-M, DCLI-176 
names of installed files, DCL N-Z, 
DCLI-257, DCLII—260 
names of open files, DCL N-Z, DCLII—257 
on current output device, DCL N-Z, 
DCLH-424 
owner UIC, DCL A-M, DCLI-172 
protection, DCL A-M, DCLI-173 
dumping, DCL A-M, DCLI-188 
editing 
with EDT editor, DCL A-M, DCLI-197 
with SUMSLP editor, DCL A-M, 
DCLI-202 
with TECO editor, DCL A-M, DCLI-203 
formatting text 
See DSR 
ignoring characters, strings, or records in 
comparisons, DCL A-M, DCLI-161 
list in directory, DCL A-M, DCLI-168 
maximum number on disk, DCL A-M, 
DCLI-258 
modifying characteristics, DCL N-Z, 
DCLII-131 
modifying queue entries for, DCL N-Z, 
DCLII-121 
modifying RMS defaults for file operations, 
DCL N-Z, DCLII-196 
opening, DCL N-Z, DCLI-6 
printing, DCL N-Z, DCLII-14 
purging, DCL N-Z, DCLIJ-28 
queue and journal, DCL N-Z, DCLII-384 
reading records from, DCL N-Z, DCLII-—82 
renaming, DCL N-Z, DCLII-39 
searching for character string, DCL N-Z, 
DCLII-69 
transferring, DCL A-M, DCLI-218 
unlocking, DCL N-Z, DCLII-431 


Files (cont’d) 
updating with SUMSLP editor, DCL A-M, 
DCLI-202 
version limit 
defining at directory creation, DCL A-M, 
DCLI-97 
writing records to, DCL N-Z, DCLII-435 
Files—11 
initializing disks, DCL A-M, DCLI-253 
On-Disk Structure Level 1 format, DCL A-M, 
DCLI-253 
Files—11 volumes 
modifying characteristics of, DCL N-Z, 
DCLII-231 
File shareable images 
analyzing, DCL A-M, DCLI-22 
File system requests 
responding to, DCL N-Z, DCLII-44 
File types 
changing, DCL N-Z, DCLII-39 
File version numbers 
changing, DCL N-Z, DCLII-39 
File windows 
mapping pointer allocation, DCL A-M, 
DCLI-261 
specifying mapping pointers, DCL N-Z, 
DCLI-233 
FONT command, DCL A-M, DCLI-231 
Formatting 
of DIFFERENCES output, DCL A-M, 
DCLI-162 


G 


Generic device names, DCL A-M, DCLI-15 
Generic queues, DCL A-M, DCLI-264 
initializing, DCL A-M, DCLI-271; DCL N-Z, 
DCLII-377 
starting, DCL A-M, DCLI-265 
stopping, DCL A-M, DCLI-265 
Global symbol directories 
See GSDs 
Global symbols, DCL A-M, DCLI-1, DCLI-5 
Global symbol tables 
See GSTs 
GOSUB command, DCL A-M, DCLI-232, 
DCLI-233 
GOTO command, DCL A-M, DCLI-234, 
DCLI-235 
Granularity hint regions (GHR), DCL N-Z, 
DCLII-—298 
Group logical name tables 
canceling entries, DCL A-M, DCLI-112 
including logical name, DCL A-M, DCLI—42, 
DCLI-121 


GSDs (global symbol directories) 
analyzing in object files, DCL A-M, DCLI-28 
GSTs (global symbol tables) 
analyzing, DCL A-M, DCLI-23 
deleting symbols from, DCL A-M, DCLI-151 
entering symbol in, DCL A-M, DCLI-279 


H 


Header allocation 
on disk volumes, DCL A-M, DCLI-—257 
HELP command, DCL A-M, DCLI-236 to 
DCLI-243 
Help display 
of default libraries, DCL A-M, DCLI-237 
Help files, DCL A-M, DCLI-236 
Help libraries 
creating, DCL A-M, DCLI-236 
user, DCL A-M, DCLI-240 
HELP/MESSAGE command, DCL A-M, DCLI-244 
to DCLI-249 
Hexadecimal dump, DCL A-M, DCLI-190 
Hibernation 
See RUN command 


IF command, DCL A-M, DCLI-250 to DCLI-252 
Image files, DCL A-M, DCLI-22 to DCLI-24 
See also PATCH command 
analyzing, DCL A-M, DCLI-22 
analyzing fixup section, DCL A-M, DCLI-23 
analyzing global symbol table, DCL A-M, 
DCLI-23 
analyzing patch text records, DCL A-M, 
DCLI-24 
error analyzing of, DCL A-M, DCLI-22 
invoking, DCL N-Z, DCLII-12 
Images 
continuing execution of, DCL A-M, DCLI-64 
executing in detached process, DCL N-Z, 
DCLII-58 
executing in subprocess, DCL N-Z, DCLII-58 
hibernation 
See RUN command 
resuming execution of, DCL A-M, DCLI-64 
running, DCL N-Z, DCLI-56 
specifying size with the RUN command, DCL 
N-Z, DCLII-62 
terminating with EXIT command, DCL A-M, 
DCLI-227 
wakeup 
See RUN command 
Indexes 
creating source file with DSR, DCL N-Z, 
DCLII-68 
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Index files 
placing on disk, DCL A-M, DCLI-258 
INITIALIZE command, DCL A-M, DCLI-253 to 
DCLI-262 
INITIALIZE/QUEUE command, DCL A-M, 
DCLI-263 to DCLI-277 
Initializing 
queues, DCL A-M, DCLI-263 
tapes 
using REPLY/BLANK_TAPE, DCL N-Z, 
DCLII-44 
using REPLY/INITIALIZE_TAPE, DCL 
N-Z, DCLITI-44° 
volumes, DCL A-M, DCLI-253 
Input converter 
DDIF, DCL A-M, DCLI-67 
DTIF, DCL A-M, DCLI-68 
Text, DCL A-M, DCLI-69 
Input data stream 
marking beginning of, DCL A-M, DCLI-117 
marking end of, DCL A-M, DCLI-211 
Input streams 
defining for created process, DCL N-Z, 
DCLH-58 
switching control to other processes, DCL A-M, 
DCLI-50 
INQUIRE command, DCL A-M, DCLI-278 to 
DCLI-—280 
INSTALL command, DCL A-M, DCLI-281 
Interactive help, DCL A-M, DCLI-239 


J 


Job batch cards 
end of, DCL A-M, DCLI-213 
JOB card password, DCL N-Z, DCLII-—10 
JOB command, DCL A-M, DCLI-282 to 
DCLI-287 
Job logical name tables 
canceling entries, DCL A-M, DCLI-112 
including logical name, DCL A-M, DCLI-43, 
DCLI-122 
Job retention 
determining, DCL N-Z, DCLII-22, DCLII—127, 
DCLII—417 
Jobs 
defining CPU time limit, DCL A-M, DCLI-—268; 
DCL N-Z, DCLIT—184, DCLII-375 
deleting from queue, DCL A-M, DCLI-141, 
DCLI-148 
redirecting to another queue, DCL A-M, 
DCLI-47 
removing from queue 
with ASSIGN/MERGE command, DCL 
A-M, DCLI-47 
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Kept Debugger, DCL A-M, DCLI-116 
Keypad applications 
setting for DECterm, DCL A-M, DCLI-105 


L 


Labels 
command interpreter rules for, DCL A-M, 
DCLI-53, DCLI-232, DCLI-234 
in command procedures, DCL A-M, DCLI-53, 
DCLI-232, DCLI-234 
specifying for volumes, DCL N-Z, DCLII—232 
volume header, DCL A-M, DCLI-253 
writing on volume, DCL A-M, DCLI-253 
Lexical functions, DCL A-M, DCLI-290 
overview, DCL A-M, DCLI-288 
Libraries 
object module, DCL A-M, DCLI-28 
LIBRARY command, DCL A-M, DCLI-412 
LICENSE command, DCL A-M, DCLI-413 
Licenses 
displaying active, DCL N-Z, DCLII-283 


LINK command, DCL A-M, DCLI-414 


Link option specification records 
analyzing in object files, DCL A-M, DCLI-28 
Listing files in directory, DCL A-M, DCLI-168 
Local symbols, DCL A-M, DCLI-1, DCLI-5 
Local symbol tables 
deleting symbols from, DCL A-M, DCLI-151 
entering symbol in, DCL A-M, DCLI-279 
Lock limits 
specifying for detached processes, DCL N-Z, 
DCLII-62 
specifying for subprocesses, DCL N-Z, 
DCLII-62 
Logging in, DCL A-M, DCLI-415 to DCLI-418 
Logging out, DCL A-M, DCLI-419 
and device accesses, DCL A-M, DCLI-15 
Logical name inclusion 
in group logical name tables, DCL A-M, 
DCLI-42, DCLI-121 
in job logical name tables, DCL A-M, DCLI-43, 
DCLI-122 
in process logical name tables, DCL A-M, 
DCLI-43, DCLI-122 
in system logical name tables, DCL A-M, 
DCLI-48, DCLI-122 
Logical names 
assigning, DCL A-M, DCLI-41, DCLI-120 
assigning to devices, DCL A-M, DCLI-15 
canceling, DCL A-M, DCLI-111 
creating, DCL A-M, DCLI-41, DCLI-120 
creating a table, DCL A-M, DCLI-100 
deassigning using CLOSE command, DCL 
A-M, DCLI-59 


Logical names (cont'd) 
displaying 
equivalence name for, DCL N-Z, 
DCLIT-291, DCLII-354 
translation of, DCL N-Z, DCLII-291, 
DCLII-354 
process-permanent, DCL N-Z, DCLII-58 
Logical name tables 
canceling entries, DCL A-M, DCLI-113 
canceling system entries, DCL A-M, DCLI-113 
creating, DCL A-M, DCLI-—100 
deleting, DCL A-M, DCLI-111 
displaying, DCL N-Z, DCLII-291 
including logical names, DCL A-M, DCLI-43, 
DCLI-122 
including system logical name, DCL A-M, 
_ DCLI-43, DCLI-122 
Logical queues, DCL A-M, DCLI-265 
deassigning, DCL A-M, DCLI-115 
Login command procedures 
executing, DCL A-M, DCLI-415 
specifying alternate, DCL A-M, DCLI-415 
LOGINOUT-EXE file 
and detached processes, DCL N-Z, DCLII-61 
LOGOUT command, DCL A-M, DCLI-419 | 
message, DCL A-M, DCLI-419 
multiple, DCL A-M, DCLI-419 
Longword dump, DCL A-M, DCLI-190 


M 


MACRO-32 compiler, DCL A-M, DCLI-420 


MACRO-32 Compiler, DCL A-M, DCLI-427 
MACRO command, DCL A-M, DCLI-420 to 
DCLI—426 
MACRO/MIGRATION command, DCL A-M, 
DCLI-427 
Mailboxes . 
process termination, DCL N-Z, DCLII-63 
MAIL command, DCL A-M, DCLI-428 
Mail utility (MAIL), DCL A-M, DCLI-428 
-Managers, queue 
See Queue managers: 
Match size 
specifying with DIFFERENCES command, 
DCL A-M, DCLI-—162 
/MEDIA_FORMAT qualifier 
for INITIALIZE command, DCL A-M, 
DCLI-259; DCL N-Z, DCLII-163 
Memory 
displaying availability and use of 
process balance slots, DCL N-Z, 
DCLII-297 
_ process entry slots, DCL N-Z, DCLII—297 
displaying error count for, DCL N-Z, 
DCLII-275 
examining contents, DCL A-M, DCLI-214 
modifying, DCL A-M, DCLI-153 


Memory (cont'd) 
replacing contents, DCL A-M, DCLI-153 
MERGE command, DCL A-M, DCLI-—429 
Merging 
of DIFFERENCES, DCL A-M, DCLI-163 
queues, DCL A-M, DCLI-47 
MESSAGE command, DCL A-M, DCLI-430 
Message files 
setting format, DCL N-Z, DCLII-165 
Message logging 
CONVERT/DOCUMENT command, DCL A-M, 
DCLI-70 
Messages 
online documentation, DCL A-M, DCLI-244 
sending to terminals, DCL N-Z, DCLII-43 
Modes of transferring files, DCL A-M, DCLI-220 
Module header records 
analyzing in object files, DCL A-M, DCLI-28 
Module objects 
analyzing, DCL A-M, DCLI-26 
analyzing end-of-file records, DCL A-M, 
DCLI-27 
Module traceback records 
analyzing in object files, DCL A-M, DCLI-28 
MONITOR command, DCL A-M, DCLI-431 
MOUNT command, DCL A-M, DCLI-432 
See also DEASSIGN command 
See also DISMOUNT command 
Movefile 
controlling whether movefile operations are 
enabled, DCL N-Z, DCLII-134 
determining if movefile operations are enabled, 
DCL A-M, DCLI-324 
Multiprocessing systems 
showing attached processor state, DCL N-Z, 


DCLII-249 
starting attached processor, DCL N-Z, 
DCLII-370 
stopping attached processors, DCL N-Z, 
DCLII-392 
N 
Names 


See also Logical names 
detached processes, DCL N-Z, DCLII-60 
generic devices, DCL A-M, DCLI-15 
logical 
canceling, DCL A-M, DCLI-111 
deassigning, DCL A-M, DCLI-59 
subprocesses, DCL N-Z, DCLII-60 
symbol definition, DCL A-M, DCLI-1, DCLI-5 
National character set (NCS) utility, DCL N-Z, 
DCLII-1 
NCS command, DCL N-Z, DCLIIJ-1 
NCS utility 
See National character set (NCS) utility 
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Network nodes 
See also SET HOST command 
See also SET HOST/DUP command 
See also SET HOST/HSC command 
and batch jobs, DCL N-Z, DCLII—416 
connecting to a HSC, DCL N-Z, DCLII-—150 
connecting to a remote processor, DCL N-Z, 

DCLII-138 


connecting to a storage controller, DCL N-Z, | 


DCLII-148 
Node names ; 
displaying, DCL N-Z, DCLII-356 
Non OpenVMS systems 
specifying remote files on, DCL A-M, DCLI-91 
Nonpaged dynamic memory 
displaying availability and use of, DCL N-Z, 
DCLII-297 


O 


Object files 
analyzing, DCL A-M, DCLI-26 
identifying 
errors, DCL A-M, DCLI-26 | 
Object module libraries, DCL A-M, DCLI-28 
Object modules 
analyzing, DCL A-M, DCLI-26 
end-of-file records, DCL A-M, DCLI-27 
Octal dump, DCL A-M, DCLI-191 
ON command, DCL N-Z, DCLII-—2 to DCLIJ—-5 
Online help, DCL A-M, DCLI-236 
OPCOM (operator communication manager) 
enabling terminal to receive messages from, 
DCL N-Z, DCLII—45 
messages to users from, DCL N-Z, DCLII-52 > 
OPEN command, DCL N-Z, DCLII-6 to DCLII-9 
Open files, DCL N-Z, DCLII-6 
displaying names, DCL N-Z, DCLII-257 
Opening of queue and journal files, DCL N-Z, 
DCLII-384 
OpenVMS RMS 


See RMS 
Operator communication manager 
See OPCOM 
Operators (computer) 
See also REQUEST command 
disabling status, DCL N-Z, DCLII-45 
enabling status, DCL N-Z, DCLII—-45 
log file closing, DCL N-Z, DCLII-46 
log file opening, DCL N-Z, DCLII-—46 
requesting replies from, DCL N-Z, DCLI-52 
sending requests to, DCL N-Z, DCLII-52 
Options files 
CONVERT/DOCUMENT command, DCL A-M, 
DCLI-71 
creating, DCL A-M, DCLI-71 
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Output converter 
analysis, DCL A-M, DCLI-67 
DDIF, DCL A-M, DCLI-68 
DTIF, DCL A-M, DCLI-69 
PostScript, DCL A-M, DCLI-70 
Text, DCL A-M, DCLI-—70 


Output queues 


See Queues 
Output streams 
defining for created process, DCL N-Z, 
DCLII-58 
Overlaying files using the COPY command, DCL 
A-M, DCLI-84 
Overriding 
default command interpreter, DCL A-M, 
DCLI-415 
magnetic tape overwrite protection, DCL A-M, 
DCLI-259 
owner identification field, DCL A-M, DCLI-259 
Owner identifier field 
writing characters to, DCL A-M, DCLI-258 
Ownership 
specifying for volumes, DCL A-M, DCLI-260 


p 


/PAGE=SAVE qualifier navigation keys, DCL 
A-M, DCLI-164, DCLI-173, DCLI-191, 
DCLI-238; DCL N-Z, DCLII-73, DCLII-244, 
DCLII-—258, DCLII-—264, DCLII-272, 
DCLII-—276, DCLII—284, DCLII~293, 
DCLII-299, DCLII-312, DCLII-322, 
DCLII-344, DCLII-357, DCLII—428 

Paged dynamic memory 

displaying availability and use of, DCL N-Z, 
DCLIT—297 

Parameters 

passing to batch jobs, DCL N-Z, DCLII-415 

passing to command procedures, DCL A-M, 
DCLI-9, DCLI-53 

specifying for command procedures, DCL A-M, 
DCLI-9 

PASSWORD command, DCL N-Z, DCLII-10 to 
DCLII-11 

Passwords 

changing, DCL N-Z, DCLII-169 

setting, DCL N-Z, DCLII-169 

setting at login, DCL A-M, DCLI-415 
PATCH command, DCL N-Z, DCLII-—12 
Patch text records 

analyzing, DCL A-M, DCLI-24 
Patch utility (PATCH) | 

changing code in, DCL N-Z, DCLII-12 

invoking, DCL N-Z, DCLII-—12 

Pausing queues, DCL N-Z, DCLII-394 


PHONE command, DCL N-Z, DCLII-13 
Physical memory 
displaying availability and use of, DCL N-Z, 
DCLII-297 
Ports 
displaying information, DCL N-Z, DCLII-—356 
PostScript output converter, DCL A-M, DCLI-70 
processing options, DCL A-M, DCLI-73 
PRINT command, DCL N-Z, DCLII-14 to 
DCLIT-25 
files, DCL N-Z, DCLII-14 
procedure in batch job log, DCL N-Z, 
DCLII-228 
Print queues 


See Queues 
Priorities 
modifying processes, DCL N-Z, DCLIT-177 
specifying for batch jobs, DCL N-Z, DCLH-416 
specifying for detached processes, DCL N-Z, 
DCLII-64 
specifying for subprocesses, DCL N-Z, 
DCLII-64 
Privileges 
displaying processes, DCL N-Z, DCLII-313 
modifying processes, DCL N-Z, DCLII-177 
specifying for subprocesses, DCL N-Z, 
DCLII-64 
Process dumps 
analyzing of, DCL A-M, DCLI-30 
Processes 
See also Subprocesses 
displaying , 
buffered I/O count, DCL N-Z, DCLII—339 
characteristics of, DCL N-Z, DCLII-310 
CPU time used, DCL N-Z, DCLII-339 
current physical memory occupied, DCL 
N-Z, DCLII-339 
current working set size, DCL N-Z, 
DCLII-339 
identification, DCL N-Z, DCLII-311 
information on, DCL N-Z, DCLII-237 
names, DCL N-Z, DCLII-356 
open file count, DCL N-Z, DCLII-—339 
page faults, DCL N-Z, DCLII-339 
privilege, DCL N-Z, DCLII-313 
status, DCL N-Z, DCLII-339 
updated information about, DCL N-Z, 
DCLII-311, DCLII-312 
displaying list of systems processes, DCL N-Z, 
DCLII-342 
hibernation 
with ATTACH command, DCL A-M, 
DCLI-—50 
image wakeup, DCL N-Z, DCLII-60 
modifying characteristics of, DCL N-Z, 
DCLII-177 
modifying working set default size, DCL N-Z, 
DCLII-235 


Processes (cont'd) 
placing in wait state, DCL N-Z, DCLII—433 
priority 
for detached processes, DCL N-Z, 
DCLII-64 
for subprocesses, DCL N-Z, DCLII-64 
privileges 
specifying for subprocesses, DCL N-Z, 
DCLII-64 
setting default devices or directories, DCL N-Z, 
DCLII-107 
status 
displaying current, DCL N-Z, DCLII-339 
swap mode 
enabling or disabling, DCL N-Z, 
DCLII-179 
swapping 
for created processes, DCL N-Z, DCLII—65 
switching control of input stream, DCL A-M, 
DCLI-50 
synchronizing with batch job, DCL N-Z, 
DCLIT-422 
working set 
displaying quota and limit, DCL N-Z, 
DCLI-361 
Processing options 
analysis output converter, DCL A-M, DCLI-71 
domain converter, DCL A-M, DCLI-75 
in an options file, DCL A-M, DCLI-71 
PostScript output converter, DCL A-M, 
DCLI-73 
text output converter, DCL A-M, DCLI-72 
Processors 
showing state of attached, DCL N-Z, 
DCLII-249 
showing state of secondary, DCL N-Z, 
DCLII-—249 
starting attached, DCL N-Z, DCLII-370 
starting secondary, DCL N-Z, DCLII-370 
stopping attached, DCL N-Z, DCLII-—392 
stopping secondary, DCL N-Z, DCLII-392 
PRODUCT command, DCL N-Z, DCLII—-26 
Programs 
continuing execution of, DCL A-M, DCLI-64 
marking beginning of input stream, DCL A-M, 
DCLI-117 . 
marking end of input stream, DCL A-M, 
DCLI-211 
resuming execution of, DCL A-M, DCLI-64 
Prompts mo 
displaying in command procedures, DCL A-M, 
DCLI-278 
Protection 
default at disk initialization, DCL A-M, 
DCLI-256 
defining at directory creation, DCL A-M, 
DCLI-97 
defining at file creation, DCL A-M, DCLI-94 
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Protection (cont’d) 
disk volumes, DCL A-M, DCLI-260 
displaying default, DCL N-Z, DCLII-318 
displaying security profiles, DCL N-Z, 
DCLII-335 
establishing default, DCL N-Z, DCLII-182 
magnetic tape volumes, DCL A-M, DCLI-260 
modifying security profiles, DCL N-Z, 
DCLII-200 
PSWRAP command, DCL N-Z, DCLII-27 
PURGE command, DCL N-Z, DCLII-28 to 
DCLI-31 
Purging files, DCL N-Z, DCLII-—28 


See also Deleting 


Q 


Queue and journal files, DCL N-Z, DCLII-384 
Queue database files 
closing, DCL N-Z, DCLII-399 
Queue managers 
failover, DCL N-Z, DCLIT-885 
restarting, DCL N-Z, DCLII-385, DCLII-399 
starting, DCL N-Z, DCLII-384 
. stopping, DCL N-Z, DCLII-399 
Queue options 
assigning, DCL N-Z, DCLII-—372 
changing, DCL A-M, DCLI-263; DCL N-Z, 
DCLII-872 
Queues 


See also Print queues 

activating autostart, DCL A-M, DCLI-—207; 
DCL N-Z, DCLII-372 

assigning, DCL A-M, DCLI-263 

assigning logical names to, DCL A-M, DCLI-48 

assigning to devices, DCL A-M, DCLI-48 

autostart, DCL A-M, DCLI-266; DCL N-Z, 
DCLII-373 

batch jobs 
displaying entries, DCL N-Z, DCLII-270, 

DCLIJ-319 
entering command procedures in, DCL 
N-Z, DCLIT-410 

changing entries for batch and printer jobs, 
DCL N-Z, DCLII-121 

changing options on, DCL A-M, DCLI-263; 
DCL N-Z, DCLII-372 

creating, DCL A-M, DCLI-263 

deactivating autostart, DCL N-Z, DCLII—400, 
DCLII-404 

deassigning, DCL A-M, DCLI-115 

defining CPU time limit for batch jobs, DCL 
A-M, DCLI-268; DCL N-Z, DCLII-184, 
DCLII-375 

defining default working sets for batch jobs, 
DCL A-M, DCLI-275, DCLI-285; DCL 
N-Z, DCLIT-188, DCLII-381, DCLIT-418 
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Queues (cont'd) 

defining working set extent for batch jobs, DCL 
A-M, DCLI-275, DCLI-285; DCL N-Z, 
DCLIT-188, DCLII-381, DCLII—419 

defining working set quotas for batch jobs, 
DCL A-M, DCLI-285; DCL N-Z, 
DCLII-189, DCLII-381, DCLIT—419 

deleting batch or print, DCL A-M, DCLI-148 

deleting entries, DCL A-M, DCLI-141 

designating as autostart, DCL A-M, DCLI-265 

disabling autostart, DCL A-M, DCLI-180; 
DCL N-Z, DCLII—406 

displaying default characteristics of system 

' print queues, DCL N-Z, DCLII-308 

displaying device entries, DCL N-Z, 
DCLII-270, DCLII-319 

displaying entries, DCL N-Z, DCLII-319 

ensuring availability of, DCL A-M, DCLI-266; 
DCL N-Z, DCLII-373 

establishing a print queue as spooled, DCL 
N-Z, DCLII-109 

establishing base priority for batch jobs, DCL 
N-Z, DCLII-183 

establishing base priority for jobs, DCL A-M, 
DCLI-266 

execution of, DCL A-M, DCLI-264 
designating autostart or nonautostart, 

DCL A-M, DCLI-265 

failover of, DCL A-M, DCLI-266; DCL N-Z, 
DCLIT-373 

generic, DCL A-M, DCLI-264 

initializing, DCL A-M, DCLI-263 

logical, DCL A-M, DCLI-265 

merging jobs, DCL A-M, DCLI-47 

modifying characteristics of a print queue, 
DCL N-Z, DCLII-174 

pausing, DCL N-Z, DCLII-394 

preparing for a shutdown, DCL N-Z, 
DCLIT—407 

preventing failover, DCL A-M, DCLI-180 

reinitializing existing, DCL A-M, DCLI-263 — 

releasing from paused states, DCL N-Z, 
DCLII-394 

removing jobs from, DCL A-M, DCLI-47 

restarting, DCL N-Z, DCLII-372, DCLII—400, 
DCLIT-404 
See also Queues, releasing from paused 

state 

See also Queues, starting 

restarting after deactivating for autostart, 
DCL N-Z, DCLII-400, DCLIT-404 

server, DCL A-M, DCLI-265 

setting up for failover, DCL A-M, DCLI-266; 
DCL N-Z, DCLII-373 

starting, DCL N-Z, DCLII-372 

starting autostart, DCL A-M, DCLI-207; DCL 
N-Z, DCLII-872 


Queues (cont'd) 
starting queue managers, DCL N-Z, 
DCLII-384 
stopping, DCL N-Z, DCLII-372, DCLII—400, 
DCLIT—-404 
all, DCL N-Z, DCLII—406 
before shutdown, DCL A-M, DCLI-—180; 
DCL N-Z, DCLII—406 
queue managers, DCL N-Z, DCLII-399 
symbionts, DCL A-M, DCLI—265 
types of, DCL A-M, DCLI-264 
Quotas 
AST limit, DCL N-Z, DCLII-61 
batch jobs 
working set, DCL N-Z, DCLII-419 
CPU 
for created processes, DCL N-Z, DCLII-65 
of subprocesses process can create, DCL N-Z, 
DCLII-65 
working set 
for batch jobs, DCL N-Z, DCLII-419 
modifying, DCL N-Z, DCLII—235 
Quotation marks (“ ”) 
in remote file specifications, DCL A-M, 
DCLI-91 


R 


Read check - . 
with APPEND command, DCL A-M, DCLI-39 
with COPY command, DCL A-M, DCLI-84 
with INITIALIZE command, DCL A-M, 
DCLI-255 
READ command, DCL N-Z, DCLII-32 to 
DCLII-35 
Ready access 
for directories on diske DCL A-M, DCLI-254 
RECALL command, DCL N-Z, DCLII-386 to 
DCLII-38 
Record Management Services 


See RMS 
Records 
analyzing 
debugger information, DCL A-M, DCLI-27 
global symbol directory, DCL A-M, 
DCLI-28 
link option specification, DCL A-M, 
DCLI-28 
module header, DCL A-M, DCLI-28 
module traceback, DCL A-M, DCLI-28 
patch text, DCL A-M, DCLI-24 
relocation, DCL A-M, DCLI-29 
analyzing end-of-file, DCL A-M, DCLI-27 
comparing, DCL A-M, DCLI-—158 
reading, DCL N-Z, DCLII-32 
writing to a file, DCL N-Z, DCLU-4385 


Recovering 
EDT editing session, DCL A-M, DCLI-199 
Releasing queues from paused states, DCL N-Z, 
DCLII-394 
Relocation records 
analyzing in object files, DCL A-M, DCLI-29 
Remote files 
specifying, DCL A-M, DCLI-91 
RENAME command, DCL N-Z, DCLII-89 to 
DCLII-42 
REPLY command, DCL N-Z, DCLII-48 to 
DCLII-51 
See also INITIALIZE command 
See also MOUNT command 
See also REQUEST command 
disabling operator status, DCL N-Z, DCLII-—45 
enabling operator status, DCL N-Z, DCLII-45 
responding to file system requests, DCL N-Z, 
DCLIT—-44 
responding to user requests, DCL N-Z, 
DCLII-44 
REQUEST command, DCL N-Z, DCLIJ-52 to 
DCLII-53 
Restarting 
deactivated autostart queues, DCL N-Z, 
DCLII-400, DCLII-—404 
queues, DCL N-Z, DCLII-372 
See also Starting queues 
stopped queues, DCL N-Z, DCLII-—400, 
DCLII-+404 
the queue manager, DCL N-Z, DCLII-385, 
DCLII-399 
Restarting a queue 
See Releasing queues from paused states 
Resuming execution — 
of command procedure, DCL A-M, DCLI-64 
of DCL commands, DCL A-M, DCLI-64 
of program, DCL A-M, DCLI-64 
RETURN command, DCL N-Z, DCLII-54 to 
DCLII-55 
Return key 
to log in, DCL A-M, DCLI-415 
Rights lists 
modifying, DCL N-Z, DCLII-193 
RMS 
displaying default block count, DCL N-Z, 
DCLII-334 
modifying defaults for, DCL N-Z, DCLII—-196 
Runaway tapes 
stopping, DCL A-M, DCLI-254 
RUN command 
See also ATTACH command . 
See also SPAWN command 
with images, DCL N-Z, DCLI-56, DCLII—-57 
abbreviating, DCL N-Z, DCLII-56 
with processes, DCL N-Z, DCLII-58 to 
DCLII-67 


Index—15 


RUN command 
with processes (cont’d) 
creating detached processes, DCL N-Z, 
DCLII-—66 
Runoff 
See DSR 


S 


Screen-oriented editors 
EDT, DCL A-M, DCLI-197 
EVE, DCL A-M, DCLI-206 
SEARCH command, DCL N-Z, DCLII-69 to 
DCLII-76 
Search lists, DCL A-M, DCLI-41, DCLI-120 
Security 
object protection, DCL N-Z, DCLII-—200, 
DCLII-335 
Security auditing, DCL N-Z, DCLII-83 
Server queues, DCL A-M, DCLI-265 
SET ACCOUNTING command, DCL N-Z, 
DCLII-—80 to DCLII-82 
SET AUDIT command, DCL N-Z, DCLII-83 to 
DCLII-95 
SET BROADCAST command, DCL N-Z, 
DCLII-96 to DCLII-—97 
SET CARD_READER command, DCL N-Z, 
DCLII-98 
SET CLUSTER/EXPECTED_VOTES command, 
DCL N-Z, DCLII-99 to DCLII-100 
SET command, DCL N-Z, DCLII-77 to DCLII-79 
SET COMMAND command, DCL N-Z, DCLII-101 
to DCLII—103 
SET CONTROL command, DCL N-Z, DCLII-104 
to DCLII-—105 
SET DAY command, DCL N-Z, DCLII-106 
SET DEFAULT command, DCL N-Z, DCLII—107 
to DCLII—108 
SET DEVICE command, DCL N-Z, DCLII-—109 to 
DCLII—110 
SET DEVICE/SERVED command, DCL N-Z, 
DCLII-111 
SET DIRECTORY command, DCL N-Z, 
DCLII-112 to DCLII—114 
SET DISPLAY command, DCL N-Z, DCLII-115 to 
DCLII-—120 
SET ENTRY command, DCL N-Z, DCLII-121 to 
DCLII-—130 
SET FILE command, DCL N-Z, DCLII-131 to 
DCLII-137 ; 
SET HOST command, DCL N-Z, DCLII—138 to 
DCLII-140 
See also Network nodes 
SET HOST/DTE command, DCL N-Z, DCLII-141 
SET HOST/DUP command, DCL N-Z, DCLII-148, 
DCLII-149 
See also Network nodes 
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SET HOST/HSC command, DCL N-Z, DCLII-150, 
DCLII-151 
See also Network nodes 
SET HOST/LAT command, DCL N-Z, DCLII~152 
to DCLII—156 . 
SET HOST/RLOGIN command, DCL N-Z, 
DCLII-157 to DCLII—-158 


SET HOST/TELNET command, DCL N-Z, 


DCLII-159 
SET HOST/TN3270 command, DCL N-Z, 
DCLII-160 . 
SET KEY command, DCL N-Z, DCLII-161 
SET LOGINS command, DCL N-Z, DCLII-162 
SET MAGTAPE command, DCL N-Z, DCLII-163, 
DCLIT-164 ‘ 
SET MAGTAPE/RETENSION command, DCL 
N-Z, DCLII-163 
SET MESSAGE command, DCL N-Z, DCLII-165, 
DCLII-166 
SET ON command, DCL N-Z, DCLII~167 
SET OUTPUT_RATE command, DCL N-Z, 
DCLII-168 
SET PASSWORD command, DCL N-Z, 
DCLII-169 to DCLIT-171 
SET PREFIX command, DCL N-Z, DCLII-172, 
DCLII-173 
SET PRINTER command, DCL N-Z, DCLII-174 
to DCLII—-176 
SET PROCESS command, DCL N-Z, DCLII-177 
to DCLII-180 
SET PROMPT command, DCL N-Z, DCLII-181 
SET PROTECTION/DEFAULT command, DCL 
N-Z, DCLII-182 
SET QUEUE command, DCL N-Z, DCLII-183 to 
DCLII-—190 
SET RESTART_VALUE command, DCL N-Z, 
DCLIIJ~191 to DCLII-192 
SET RIGHTS_LIST command, DCL N-Z, 
DCLII-193 to DCLII-195 
attributes, DCL N-Z, DCLII-193 
Dynamic, DCL N-Z, DCLII-—193 
No Access, DCL N-Z, DCLII-193 
Resource, DCL N-Z, DCLII-193 
Subsystem, DCL N-Z, DCLII-193 
SET RMS_DEFAULT command, DCL N-Z, 
DCLII-196 to DCLIT-199 
SET SECURITY command, DCL N-Z, DCLII-—200 
to DCLII—207 
SET SYMBOL command, DCL N-Z, DCLII-210 to 
DCLII-212 
SET TERMINAL command, DCL N-Z, DCLII-213 
to DCLII—-225 
See also SHOW TERMINAL command 
SET TIME command, DCL N-Z, DCLII—226 to 
DCLII-227 


SET VERIFY command, DCL N-Z, DCLIJ-228 to 
DCLII-230 
SET VOLUME command, DCL N-Z, DCLII-231 
to DCLII-234 
SET WORKING_SET command, DCL N-Z, 
DCLII-235, DCLII~236 
$SEVERITY global symbol, DCL N-Z, DCLII-167 
changing, DCL A-M, DCLI-227; DCL N-Z, 
DCLII-54 
Shareable images 
analyzing, DCL A-M, DCLI-22 
file analyzing, DCL A-M, DCLI-—22 
patching, DCL N-Z, DCLII-12 
Shareable volumes 
dismounting, DCL A-M, DCLI~184 
initializing disk as, DCL A-M, DCLI-260 
Shared device 
dismounting, DCL A-M, DCLI-185 
Shelving 


See also Automatic unshelving 
controlling whether file is shelvable, DCL N-Z, 
DCLII-135 
determining if file is shelvable, DCL A-M, 
DCLI—174, DCLI-325 
determining if file is shelved, DCL A-M, 
DCLI-174, DCLI-175, DCLI-325 
SHOW ACCOUNTING command, DCL N-Z, 
DCLI-240, DCLIT~241 
SHOW AUDIT command, DCL N-Z, DCLI-242 
to DCLIT—245 
SHOW BROADCAST command, DCL N-Z, 
DCLII-246, DCLIJ—247 
SHOW CLUSTER command, DCL N-Z, 
DCLII-248 
SHOW command, DCL N-Z, DCLII-—237 to 
~ DCLII-239 
summary of options, DCL N-Z, DCLII—-237 
SHOW CPU command, DCL N-Z, DCLII-249 to 
DCLIT-253 
SHOW DEFAULT command, DCL N-Z, 
DCLII-254, DCLIT—255 
SHOW DEVICES command, DCL N-Z, 
DCLII-—256 to DCLII-—262 
SHOW DEVICES/SERVED command, DCL N-Z, 
DCLII-263 to DCLIT—267 
SHOW DISPLAY command, DCL N-Z, 
DCLIT-268, DCLII-—269 
SHOW ENTRY command, DCL N-Z, DCLII-270 
to DCLII-—274 
SHOW ERROR command, DCL N-Z, DCLII-—275, 
DCLII-277 
SHOW INTRUSION command, DCL N-Z, 
DCLIT-278 to DCLII-—280 
SHOW KEY command, DCL N-Z, DCLII-281, 
DCLIT-282 


SHOW LICENSE command, DCL N-Z, 
DCLITI—283 to DCLII—290 


SHOW LOGICAL command, DCL N-Z, 


DCLII~—291 to DCLII-296 
SHOW MEMORY command, DCL N-Z, 
DCLII~297 to DCLII—306 
SHOW NETWORK command, DCL N-Z, 
DCLII-307 
SHOW PRINTER command, DCL N-Z, 
DCLI-308, DCLII-309 
SHOW PROCESS command, DCL N-Z, 
DCLH-310 to DCLI-317 
SHOW PROTECTION command, DCL N-Z, 
DCLII-318 
SHOW QUEUE/CHARACTERISTICS command, 
DCL N-Z, DCLII-326, DCLII-327 
SHOW QUEUE command, DCL N-Z, DCLII-319 
to DCLII-325 
SHOW QUEUE/FORM command, DCL N-Z, 
DCLIT-328, DCLII-329 
SHOW QUEUE/MANAGERS command, DCL 
N-Z, DCLII-330 to DCLII-332 
SHOW QUOTA command, DCL N-Z, DCLII-333 
SHOW RMS_DEFAULT command, DCL N-Z, 
DCLII-334 
SHOW SECURITY command, DCL N-Z, 
DCLII-335 to DCLII-338 
SHOW STATUS command, DCL N-Z, DCLII-339 
SHOW SYMBOL command, DCL N-Z, 
DCLII-340, DCLII-341 
SHOW SYSTEM command, DCL N-Z, DCLII-342 
to DCLII-349 
SHOW TERMINAL command, DCL N-Z, 
DCLII-350, DCLII-352 
See also SET TERMINAL command 
SHOW TIME command, DCL N-Z, DCLII-353 
SHOW TRANSLATION command, DCL N-Z, 
DCLII-354, DCLII-355 
SHOW USERS command, DCL N-Z, DCLII-356 
to DCLII-860 
SHOW WORKING_SET command, DCL N-Z, 
DCLII-361 to DCLII-362 
SHOW ZONE command, DCL N-Z, DCLII-3863 
Shutdown 
preparing a queue for, DCL N-Z, DCLII-407 
stopping autostart queues before, DCL A-M, 
DCLI-180 
stopping queues before, DCL N-Z, DCLII-406 
SORT command, DCL N-Z, DCLII-364 
SPAWN command, DCL N-Z, DCLII-365 to 
DCLII-3869 
See also ATTACH command, DCL A-M, 
DCLI-50 
START/CPU command, DCL N-Z, DCLII-—370 to 
DCLII-371 
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Starting queues, DCL N-Z, DCLII-372 
See also Restarting queues 
autostart, DCL A-M, DCLI-207, DCLI-266; 
DCL N-Z, DCLII-372 
nonautostart, DCL A-M, DCLI-266 
queue manager, DCL N-Z, DCLII-384 
START/QUEUE command, DCL N-Z, DCLII-372 
to DCLII—383 
START/QUEUE/MANAGER command, DCL N-Z, 
DCLII-—384 to DCLII-387 
START/ZONE command, DCL N-Z, DCLII-388 
Status code 
controlling command interpreter response to, 
DCL N-Z, DCLII-167 
$STATUS global symbol, DCL N-Z, DCLII-167 
changing, DCL A-M, DCLI-227; DCL N-Z, 
DCLII-54 
STOP command, DCL N-Z, DCLII-389 to 
DCLIT-391 
See also Ctrl/C key sequence 


See also Ctrl/Y key sequence 


See also EXIT command 
runaway tapes, DCL A-M, DCLI-254 
STOP/CPU command, DCL N-Z, DCLII-392, 
DCLII-393 . 
Stopping queues, DCL N-Z, DCLII-—400, 
DCLII—406 
See also Pausing queues 
abruptly, DCL N-Z, DCLII-404 
Stopping the queue managers, DCL N-Z, 
DCLII-399 
STOP/QUEUE/ABORT command, DCL N-Z, 
DCLII-—395, DCLII-396 
STOP/QUEUE command, DCL N-Z, DCLII-394 
STOP/QUEUE/ENTRY command, DCL N-Z, 
DCLII-397, DCLII-398 
STOP/QUEUE/MANAGER/CLUSTER command, 
DCL N-Z, DCLII-399 
STOP/QUEUE/NEXT command, DCL N-Z, 
DCLII-—400 
See also DELETE/QUEUE command 
STOP/QUEUE/REQUEUE command, DCL N-Z, 
DCLII—401 to DCLII—403 
STOP/QUEUE/RESET command, DCL N-Z, 
DCLII-404, DCLII—405 
STOP/QUEUES/ON_NODE command, DCL N-Z, 
DCLII—406 to DCLII—408 
STOP/ZONE command, DCL N-Z, DCLII—409 
:= (String assignment) command, DCL A-M, 
DCLI-5 to DCLI-8 
Structure levels 
defining for disks, DCL A-M, DCLI~261 
Subdirectories 
creating, DCL A-M, DCLI-96 
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SUBMIT command, DCL A-M, DCLI-285; DCL 
N-Z, DCLII-410 to DCLIT—420 
Subprocesses 


See also SPAWN command 
accounting, DCL N-Z, DCLII-60 
assigning resource quotas to, DCL N-Z, 
DCLIJ-59 
creating with RUN command, DCL N-Z, 
DCLII-58 
creating with SPAWN command, DCL N-Z, 
DCLII-365 
defining attributes, DCL N-Z, DCLII-59 
defining equivalence names for process- 
permanent logical names, DCL N-Z, 
DCLII-58 
displaying characteristics of, DCL N-Z, 
DCLII-310 
displaying quotas, DCL N-Z, DCLI-313 
image hibernation, DCL N-Z, DCLII-60 
naming with RUN/PROCESS_NAME, DCL 
N-Z, DCLII-60 
scheduling wakeup, DCL N-Z, DCLII-62 
specifying default working set, DCL N-Z, 
DCLII-66 
specifying quotas, DCL N-Z, DCLII-62 
switching control of input stream, DCL A-M,. 
DCLI-50 
SUBROUTINE command, DCL A-M, DCLI-54, 
DCLI-55; DCL N-Z, DCLII-—421 
Subroutines 
termination of GOSUB, DCL N-Z, DCLII-54 
SUMSLP editor, DCL A-M, DCLI—202 
Swapping 
for created processes, DCL N-Z, DCLII-—65 
processes 
enabling or disabling swap mode, DCL 
N-Z, DCLII-179 
Symbionts 
customer-written, DCL A-M, DCLI-265 
default, DCL A-M, DCLI-265 
special purpose, DCL A-M, DCLI-265 
Symbolic names 
defining, DCL A-M, DCLI-1, DCLI-5 
Symbols . 
assigning value with READ command, DCL 
N-Z, DCLIT-32 
binary overlay in, DCL A-M, DCLI-1 
character overlays in, DCL A-M, DCLI-6 


deleting 
from global symbol tables, DCL A-M, 
DCLI-151 
from local symbol tables, DCL A-M, 
DCLI-151 


displaying, DCL N-Z, DCLII-340 

general assignment, DCL A-M, DCLI-1 

interactive assignment in command procedures, 
DCL A-M, DCLI-278 

masking, DCL N-Z, DCLII-210 


Symbols (cont’d) 
string assignment, DCL A-M, DCLI-5 
SYNCHRONIZE command, DCL N-Z, DCLII-422 
to DCLII—423 
SYS$ERROR logical name 
specifying equivalence name with RUN 
command, DCL N-Z, DCLII-62 
SYS$INPUT logical name 
specifying equivalence name with RUN 
command, DCL N-Z, DCLII-62 
SYS$LOST directory, DCL N-Z, DCLII-134 
SYSS$OUTPUT 
displaying file on, DCL N-Z, DCLII-424 
SYS$OUTPUT logical name 
specifying equivalence name with RUN 
command, DCL N-Z, DCLII-—63 
SYS$SYLOGIN logical name 
executing, DCL A-M, DCLI-—415 
System login images 
and detached processes, DCL N-Z, DCLII-61 
System messages 
online documentation, DCL A-M, DCLI-244 
System performance 
displaying availability and use of 
resources, DCL N-Z, DCLII-—297 
Systems 
accessing, DCL A-M, DCLI-415 
changing 
date, DCL N-Z, DCLII—226 
passwords, DCL N-Z, DCLII-169 
_ time, DCL N-Z, DCLII—226 
displaying 
information on, DCL N-Z, DCLII-237 
status, DCL N-Z, DCLII—237 
System time 
changing, DCL N-Z, DCLII-—226 


T 


TA9OE tape drive 
support for, DCL N-Z, DCLII-163 
using /MEDIA_FORMAT qualifier, DCL N-Z, 
DCLII-163 
Tapes 
disabling operator status, DCL N-Z, DCLII-45 
dismounting, DCL A-M, DCLI-184 
enabling operator status, DCL N-Z, DCLIU-45 
establishing operational status for, DCL N-Z, 
DCLI-109 
initializing using REPLY command, DCL N- Z, 
DCLII-44 
modifying RMS defaults for file operations, 
DCL N-Z, DCLII-196 
TECO editor, DCL A-M, DCLI-203 
Terminal emulators 
creating, DCL A-M, DCLI-104 


Terminals 
See also SET TERMINAL command 
~ See also SHOW TERMINAL command 
default characteristics, DCL A-M, DCLI-415 
displaying characteristics of, DCL N-Z, 
DCLII-350 
displaying files at, DCL N-Z, DCLII-424 
establishing as spooled, DCL N-Z, DCLII—109 
modifying characteristics of, DCL N-Z, 
DCLII-213 
sending messages to, DCL N-Z, DCLIT-43 
virtual, DCL A-M, DCLI-61, DCLI-182 
Terminal sessions 
logging in, DCL A-M, DCLI-415 
logging out, DCL A-M, DCLI-419 
Terminations 
of command procedure, DCL A-M, DCLI-227 
of GOSUB subroutine, DCL N-Z, DCLI-—54 
of terminal session, DCL A-M, DCLI-419 
Testing 
the value of an expression, DCL A-M, 
DCLI-—250 
Text 
analyzing in object files, DCL A-M, DCLI-29 
Text editors 
See EDT editor 
See EVE editor 
See SUMSLP editor 
See TECO editor 
Text file formatting 
See DSR 
Text input converter, DCL A-M, DCLI-69 
Text output converter, DCL A-M, DCLI-70 
processing options, DCL A-M, DCLI-72 
THEN keyword 
and IF command, DCL A-M, DCLI-250 
Time 
changing system, DCL N-Z, DCLII—226 
CPU quota for created processes, DCL N-Z, 
DCLII-65 
CPU used by current process, DCL N-Z, 
DCLITI-339 
displaying, DCL N-Z, DCLII-353 
Timed retention 
specifying, DCL N-Z, DCLII-23, DCLII-128, 
DCLII-418 
TPU 
See DECTPU 
Transfer modes 
EXCHANGE/NETWORK command, DCL A-M, 
DCLI-220 
True expression 
and IF command, DCL A-M, DCLI—250 
TYPE command, DCL N-Z, DCLII-—424 to 
DCLII-430 
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TZK10 tape cartridge drives, DCL N-Z, 
DCLIT-163 


U 


UAFs (user authorization files) 
and detached processes, DCL N-Z, DCLII-61 
UICs (user identification codes) 
specifying for directories, DCL A-M, DCLI-96 
specifying for files, DCL A-M, DCLI-94 
Unloading devices 
with DISMOUNT command, DCL A-M, 
DCLI-186 
UNLOCK command, DCL N-Z, DCLII-431 
Unlocking files, DCL N-Z, DCLII-431 
User authorization files 
See UAFs 
User identification codes 
See UICs 
User libraries 
See Help libraries 
User names 
specifying at login, DCL A-M, DCLI-415 
Users 
displaying disk quota of, DCL N-Z, DCLII-333 
displaying interactive terminal name of, DCL 
N-Z, DCLII-356 
displaying names on system, DCL N-Z, 
DCLII-356 
displaying process identification code (PID) of, 
DCL N-Z, DCLII-356 
recording name on disk volume, DCL N-Z, 
DCLIT—233 
responding to requests, DCL N-Z, DCLII-44 
User-specified job retention 
PRINT/RETAIN command, DCL N-Z, 
DCLII-21 
SET ENTRY/RETAIN command, DCL N-Z, 
DCLII-127 
SUBMIT/RETAIN command, DCL N-Z, 
DCLII-—416 


V 


Value test in expression, DCL A-M, DCLI-—250 


Verification 
modifying for command procedures, DCL N-Z, 
DCLIJ-228 
Version limits 
for files in directory, DCL A-M, DCLI-97 
Version numbers 
assigning to files, DCL A-M, DCLI-221 
VIEW command, DCL N-Z, DCLII-—432 
Virtual devices, DCL A-M, DCLI-217, DCLI-339 
Virtual memory 
examining contents, DCL A-M, DCLI-214 
replacing contents, DCL A-M, DCLI—153 
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Virtual terminals 
connecting, DCL A-M, DCLI-61 
disconnecting from, DCL A-M, DCLI-182 
VMScluster envirnments 
specifying cluster size on disk, DCL A-M, 
DCLI-255 
VMScluster environments 
dismounting volumes on, DCL A-M, DCLI-185 
Volume accessibility fields 
writing characters to, DCL A-M, DCLI-258 
Volumes 
deleting disk files, DCL A-M, DCLI-136 
dismounting disk and tape, DCL A-M, 
DCLI-184 
displaying disk quota, DCL N-Z, DCLII-333 
dumping, DCL A-M, DCLI-188 
Files—11 
modifying characteristics of, DCL N-Z, 
DCLIT-231 
recording name on, DCL N-Z, DCLII-—233 
initializing, DCL A-M, DCLI-—253 
label, DCL A-M, DCLI-253 
protecting, DCL A-M, DCLI-260 
specifying maximum file number, DCL A-M, 
DCLI-258 
specifying ownership, DCL A-M, DCLI-260 
Volume sets 
dismounting, DCL A-M, DCLI-186 


W 


" WAIT command, DCL N-Z, DCLII-433 to 


DCLII-434 
Wait state 
delaying command processing, DCL N-Z, 
DCLII-433 
inducing to synchronize process with batch job, 
DCL N-Z, DCLII-422 
placing current process in, DCL N-Z, 
DCLII-433 
Wakeup requests 
canceling, DCL A-M, DCLI-57 
canceling request, DCL N-Z, DCLII-60 
scheduling with RUN command, DCL N-Z, 
DCLII-60 
Windows 
displaying size and count for open files, DCL 
N-Z, DCLII-—260 
Word dumps, DCL A-M, DCLI-192 
Working sets 
batch jobs 
defining default for, DCL A-M, DCLI—275; 
DCL N-Z, DCLII-381, DCLII-418 
defining extent for, DCL A-M, DCLI-275, 
DCLI-285; DCL N-Z, DCLII-381, 
DCLII-419 
defining quotas for batch job, DCL N-Z, 
DCLIT-381 


Working sets (cont'd) 
defining quotas for batch jobs, DCL A-M, 
DCLI-285; DCL N-Z, DCLII-189, 
DCLII-419 
displaying 
limit for process, DCL N-Z, DCLII-361 
displaying quotas, DCL N-Z, DCLII-361 
modifying default size, DCL N-Z, DCLII-235 
specifying default 
for detached processes, DCL N-Z, 
DCLII-66 


for subprocesses, DCL N-Z, DCLII-—66 
specifying quotas, DCL N-Z, DCLII-63 
Write check 
with APPEND command, DCL A-M, DCLI-39 
with COPY command, DCL A-M, DCLI-85 
with INITIALIZE command, DCL A-M, 
DCLI-255 
WRITE command, DCL N-Z, DCLII—435 to 
DCLII-437 
Writing records to a file, DCL N-Z, DCLII-435 
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NOTES 


